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The FCC Wants You to Know... 

This equipment generates and uses radio frequency energy. If not installed and used prop¬ 
erly, that is, in strict accordance with the manufacturer’s instructions, it may cause interfer¬ 
ence to radio and television reception. 

It has been type tested and found to comply with the limits for a Class B computing 
device in accordance with the specifications in Subpart J of Part 15 of FCC Rules, which are 
designed to provide reasonable protection against such interference in a residential instal¬ 
lation. However, there is no guarantee that interference will not occur in a particular 
installation. 

If this equipment does cause interference to radio or television reception, which can be 
determined by turning the equipment off and on, the user is encouraged to try to correct the 
interference by one or more of the following measures: 

• Reorient the receiving antenna 

• Relocate the computer with respect to the receiver 

• Move the computer away from the receiver 

• Plug the computer into a different outlet so that computer and receiver are on different 
branch circuits. 

If necessary, you should consult the dealer or an experienced radio/television technician for 
additional suggestions. You may find the following booklet prepared by the Federal Com¬ 
munications Commission helpful: How to Identify and Resolve Radio-TV Interference 
Problems. 

This booklet is available from the US Government Printing Office, Washington, DC 
20402, Stock No. 004-000-00345-4. 

Warning 

This equipment has been certified to comply with the limits for a Class B computing device, 
pursuant to Subpart J of Part 15 of FCC Rules. Only peripherals (computer input/output 
devices, terminals, printers, etc.) certified to comply with the Class B limits may be attached 
to this computer. Operation with non-certified peripherals is likely to result in interference to 
radio and TV reception. 
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OWNER’S MANUAL 



To Our Customers 

Congratulations on your purchase of the Model III Disk System. We think it’s a 
valuable tool which will save you work as well as give you hours of enjoyment 
(or maybe both at once). You’ll have all the power of the non-disk Model III, 
plus the following features: 

• Your Computer can now be controlled by trsdos®, the powerful trs-so Disk 
Operating System, trsdos is included on a diskette with the Disk System. 

• Using trsdos, you can run a wide variety of programs, such as the Disk basic 
interpreter included on the trsdos diskette. 

• Each “system” diskette has approximately 126,720 bytes of storage available 
for your own programs and data; each “data” diskette has 178,944 bytes 
available. 

• You can load and save data at the approximate rate of 250,000 bits per second. 

• Your system can continue to grow in power and convenience. When Radio 
Shack issues improvements and enhancements to the system programs, you 
can “install” them simply by obtaining a new release of the trsdos diskette. 




Model III Manuals 

Publications related to the use of the Model III Disk System: 

1. Model III Disk System Owner’s Manual (this manual). We’ll call it the “Disk 
Manual” for short. 

2. Model III Disk System Quick Reference Card. 

3. Model III Operation and basic Language Reference Manual, the “Model III 
Manual” for short. 

4. Model III basic Quick Reference Card. 

For Disk Operation: 

This Disk Manual supplements the Model III Manual. Use the Disk Manual as 
the primary source of information; we’ll tell you when to refer to the non-disk 
Model III Manual. 

For Non-Disk Operation: 

To use the Computer as a non-disk system, all you need is the Model III 
Manual. 

For Programming Information: 

The Model III Manual contains most of the programming information, except 
that which pertains to disk input/output. In this manual, we will assume that you 
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are familiar with the basic programming definitions and details given in the 
Model III Manual. 

About This Manual 

The Model III Disk System is intended for use by novices as well as 
experienced computer operators and programmers. In designing and writing this 
Disk Manual, we've tried to define and satisfy the needs of both groups: 

• Novices who might prefer a sequential presentation which emphasizes 
procedures and explains the purpose of various features. 

• Experienced users who might prefer a more analytical presentation which 
makes it easy to find specific information. 

In this manual, you'll find information that should satisfy your needs, whichever 
group you might belong to. 

The "Sample Sessions" are especially geared for novices, while the Technical 
Information chapters are for the more experienced users. 

Keep in mind, however, that it isn't necessary to read the entire manual to 
operate the Disk System. If you are only interested in Disk basic, for example, 
read the Operation section of this book and then turn directly to the Disk basic 
section. You can then go back to the trsdos section when you need to. 

Special Terms 

Even in the non-technical sections of this manual, we've had to use numerous 
special terms. Rather than scattering and repeating definitions throughout the 
book, we have used the following convention which we hope you'll find 
helpful. 

Special terms which are fully defined in another part of the manual are printed in 
boldface. Look up the word or phrase in the Index; this will tell you where the 
word is fully defined. 
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OPERATION 


Installation 

First set up the Computer according to the instructions in the Model III Manual. 

If you have a one- or two-drive system, installation is now complete. The built- 
in drives should be ready for use. 

If you have a three- or four-drive system, you need to connect the external 
drives. 


External Disk Drives 


The two external drives are not interchangeable. They have different Radio 
Shack Catalog Numbers and a few internal differences. 


First External Drive Purchased 
(Includes Cable) 

Second External Drive Purchased 


System 

Catalog 

Name 

Number 

Drive 2/3” 

26-1164 

Drive 2” 

26-1161 


The 26-1164 drive may be used as Drive 2 or 3, depending on the number of 
drives in the system. In a three-drive system, it is always Drive 2 (the last 
drive). In a four-drive system, it is always Drive 3 (again, the last drive). 

The 26-1161 drive may only be used in a four-drive system, in which it must be 
Drive 2. 


1. Locate the flat “ribbon” cable that was included with the 26-1164 drive. 
Notice that it has a single plug on one end, and two plugs clustered at the 
other end. See Figure 1 for plug labels. 

2. Connect the solitary “Computer” plug to the Disk Expansion Jack on the 
bottom rear of the Computer. See Figure 2. 

3. Now refer to Figure 3. Connect the external drive(s) to the other end of the 
cable, as follows: 

3-A. If you have one external drive (26-1164): 

Connect it to the “Drive 2” plug near the middle of the ribbon cable. 

3-B. If you have two external drives (26-1 164 and 26-1161): 

Connect the 26-1164 to the “Drive 3” plug on the end of the cable. 

Connect the 26-1161 to the “Drive 2” plug near the middle of the cable. 

4. Plug the external drive(s) into an appropriate source of ac power. Power 
requirements are specified on the unit and in the specifications given in this 
manual. 


You are now ready to start the Disk System. 
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Computer Plug 



Figure 1 . External Disk Cable with Plugs Labeled. 



Figure 2. Connection of the External Disk Cable to the Model III. 
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OPERATION 



Figure 3. Connection of external disk drives. 
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Operation 

First, take a few minutes to become familiar with the various elements of your 
Disk System. Refer to Figures 4 and 5. This is very important. If you try to use 
the Computer without having a little background information, you could damage 
a diskette. 



Figure 4. The Model III Disk System with External Drives (optional/extra). 


© Drive 0. The trsdos “system diskette” goes 
in this drive. 

® Drives 1, 2, and 3. These drives may 
contain “data diskettes” Data diskettes are 
described briefly in this chapter. 

© Drive Select led. When a drive is being 
accessed, its led lights up. 

© Drive Door. To insert or remove a diskette, 
open this door. Never remove a diskette 
while the led is lit, or while the diskette 
contains open files. 


© Reset Button. When you press this button, 
the Computer will attempt to load the 
operating system software from Drive 0. The 
trsdos diskette should be in Drive 0 when 
you press this button. 

© Power Switch. All drives should be empty 
when you turn the Computer on or off. 
Otherwise, the information on the diskettes 
could be destroyed. 
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Figure 5. A Diskette. (Catalog Number 26-305, 26-405, or 26-406) 


© Storage Envelope, While a diskette is not in 
use, keep it here. 


(D Write Protect Notch. When this is covered, 
the disk-drives cannot write (change infor¬ 
mation) on the diskette. Do not pinch the tab 
into the notch when you apply it. If the tab 
becomes indented, the disk drive may not 
sense that the disk is write-protected. Leave 
the notch uncovered if you want to save or 
change information on the diskette. 


(D Read/Write Window. The disk drive 
accesses the diskette surface through this 
window. Don’t touch the diskette surface. 

© Label. To write on this label, use only a felt- 
tipped pen. Any other writing implement 
might damage the diskette. 


® Jacket. The diskette is permanently sealed 
inside this protective jacket. Do not attempt 
to remove it. 


Diskettes 


In general, handle diskettes carefully, using the same precautions you use with 
tape cassettes and high-fidelity records. A small indentation, dust particle, or 
scratch can render all or part of a diskette unreadable— permanently . 

• Keep the diskette in its storage envelope whenever it is not in one of the 
drives. 

• Do not place a diskette in the drive while you are turning the system on or off. 

• Keep diskettes away from magnetic fields (transformers, ac motors, magnets, 
tvs, radios, etc.). Strong magnetic fields will erase data stored on a diskette. 
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• Handle diskettes by the jacket only. Do not touch any of the exposed surfaces. 
Don’t try to wipe or clean the diskette surface; it scratches easily. 

• Keep diskettes out of direct sunlight and away from heat. 

• Avoid contamination of diskettes with cigarette ashes, dust or other particles. 

• Do not write directly on the diskette jacket with a hard point device such as a 
ball point pen or lead pencil; use a felt tip pen only. 

• Store diskettes in a vertical file folder on a shelf where they are protected from 
pressure to their sides (just as phono records are stored). 

• In very dusty environments, you may need to provide filtered air to the 
computer room. 

Tips on Labeling Diskettes 

Each diskette has a permanent label on its jacket. This label is for “vital 
statistics” that will never change. For example, to help keep track of diskettes, 
it’s a good idea to assign a unique number to each diskette. Write such a number 
on the permanent label. You might also put your name on the diskette, and 
record the date when the diskette was first put into use. Remember, use only a 
felt tip pen for marking. 

This^'pemianent” label is not a good place to record the contents of the diskette 
since that will change, and you don’t want to be erasing or scratching out 
information from this label. 


System Start-Up 

1. Turn all peripherals on. 

2. Turn the Computer on. Wait until all disk drive motors stop. 

3. Locate the trsdos diskette that was supplied with the Disk System. Insert it 
into Drive 0, with the label side facing up and the read/write window 
pointing into the drive slot. See Figure 6. 

4. When the diskette is fully inserted, close the drive door. 

5. Press reset. The Computer should now load trsdos and begin the start-up 
dialog described in the next section. 

If nothing happens on the Display, or if the message: DISKETTE? or NOT A 

SYSTEM DISK is displayed, check the following: 

• Are you using a trsdos “system” diskette? 

• Is the diskette properly inserted into Drive 0? 

• If external drives are present, are they properly connected and turned on? 
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Figure 6. Inserting a Diskette. 

If you can’t find the problem, refer to the Troubleshooting and Maintenance 

chapter for further suggestions. 

TRSDOS Start-Up Dialog 

Whenever you reset the Model III Disk System, it loads trsdos and begins the 

start-up dialog. 

1. The trsdos version number and date of creation will be displayed, followed 
by the amount of ram <32K or 48K) and the number of drives in the system. 

2. trsdos will prompt you to enter the date in the form mm/dd/yy. For example, 
07/04/80 for July 4, 1980. Type in the correct date and press ENTER , trsdos 
will not continue until you type in the date correctly. 

3. trsdos will prompt you to enter the time in 24-hour form HH:MM:SS. For 
example, 14:45:00 for 2:45 p.m. Type in the correct time and press (ENTER) . If 
you don’t wish to set the time, simply press (ENTER) at the beginning of the 
line, trsdos will set the time to 00:00:00. 

4. trsdos will now display the message, TRSDOS READY 

Whenever this is displayed, you are in the trsdos ready mode, and you may 

type in a trsdos command. 
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Important Disk Operations 

In this section we will describe three very important operations: 

1. Duplicating the trsdos diskette (backup) 

2. Initializing a data diskette (format) 

3. Converting files from Model I to Model III trsdos (convert). 

All new customers should complete the trsdos backup procedure now; multi¬ 
drive customers should also complete the format operation for a few diskettes. 
Detailed information is provided later in this manual; here we will simply 
outline the procedures. 

Making a BACKUP (Duplicate) of TRSDOS 

Your first operation should be to duplicate the trsdos diskette you received 
from Radio Shack. The trsdos diskette contains a utility program called 
backup to accomplish this. 

1. Locate the trsdos diskette and a new, blank diskette. The trsdos diskette 
will be referred to as the “source,” while the blank one will be called the 
“destination,” during backup. 

2. Start trsdos as explained in the previous section. TRSDOS READY should be 
displayed. 

3. Type: BACKUP (ENTER) 

4. trsdos will now load and start backup. It will ask you: 

SOURCE DRIVE NUMBER? 

Specify the drive which contains the original trsdos diskette by typing: 

0 (ENTER) 

5. Next trsdos will ask: DESTINATION DRIVE NUMBER? 

Now specify the drive which will be used for making the duplicate trsdos. If 
you have two or more drives in your system, type: 1 (ENTER) 

6. TRSDOS will ask: SOURCE DISK MASTER PASSWORD? 

Type: PASSWORD (ENTER) 

(password is the password of the supplied diskette.) 

7. Now the duplication process will begin. 

If the destination diskette is not formatted, backup will format it before 
continuing. (Before any diskette can be used, it must be initialized or 
“formatted” — the data regions defined and labeled, and a table of contents 
or “directory” created.) 
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If you are using a single-drive system, trsdos will prompt you to swap 
source and destination diskettes several times during the formatting/backup 
process. 

After a single-drive backup, trsdos will display the message: 

INSERT SYSTEM DISKETTE (ENTER) 

Be sure you have a trsdos diskette in Drive 0, then press (ENTER) . 

The duplication process is now complete. We suggest you save the original 
trsdos and use the duplicate as your working copy. If anything happens to the 
working copy, you can make another one from the original. 

Making a Data Diskette (FORMAT) 

This section applies to multi-drive systems only. 

Drive 0 must always contain a trsdos diskette, so the Computer can have 
access to the system programs stored there. Much of the storage capacity of this 
diskette is taken up by the system programs. 

However, the other drives in the system may contain “data” diskettes which 
have no system programs. All of the storage capacity of such diskettes is 
available for your programs and data. 

The format utility program takes a diskette and initializes or “formats” it. 

If the diskette was previously formatted, all prior information can be lost. 

The resultant diskette contains no system files and may only be used in 
Drive 1, 2 or 3 

1 . In the trsdos ready mode, type: FORMAT (ENTER) 

2. trsdos will start the formatter program and ask you a series of questions: 
FORMAT WHICH DRIVE? 

Insert a blank diskette into Drive 1. Type: 1 (ENTER) 

DISKETTE NAME? 

This name will serve as an internal label for the diskette. Type in any 
appropriate name of one to eight letters and numbers, starting with a letter. 
Press (ENTER) at the end of the name. 

MASTER PASSWORD? 

The password may be from one to eight letters and numbers, starting with a 
letter. Press (ENTER) at the end of the password. 

Use of the password allows backup, prot, and purge access to all non¬ 
system files. Unless special protection is needed, we suggest you use the 
password password. Whatever password you select, don’t forget it! 
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If the diskette contains data, trsdos will warn you: 

DISKETTE CONTAINS DATA t USE DISK OR NOT? 

The warning is needed since format erases all previous information from the 


diskette Type N (ENTER) to cancel format; type Y (ENTER) or U ( ENTER) to 
continue it. 

3. trsdos will now format and verify the diskette. The data diskette will then 
be ready for use in Drive 1, 2, or 3. 


Model I/III Conversion (CONVERT) 


In general, Model I trsdos diskettes cannot be used in a Model III Disk 
System. However, Model III trsdos includes a special program, convert, to 
read a Model I trsdos diskette and copy its non-system files onto a Model III 
trsdos diskette. 

In two-drive systems, the files must be copied onto a Model III system diskette; 
in three- or four-drive systems, the files may be copied onto a data diskette. 

Here are abbreviated instructions for using this program. For further details, see 
convert. 

1. Using a Model I Disk System, remove all passwords from the diskette to be 
converted. You can do this with the prot command, described in the Model / 
TRSDOS/Disk basic Owner's Manual. 

2. Start Model III trsdos. 

3. Place the Model I diskette in Drive 1,2 or 3. (In two-drive systems, use 
Drive 1; in three- or four-drive systems. Drive 2.) 

4. In three- or four-drive systems, place a Model III data diskette in Drive 1. 

5. Type: CONVERT (ENTER) 

4. The conversion program will start by asking for the source drive number. 
Type in the number of the drive containing the Model I diskette, then press 


(INTER) . 


5. Next, the conversion program will ask for the destination drive number. Type 
in the number of the drive containing the Model III diskette, then press 
(ENTER ). (In two-drive systems, use Drive 0; in three- or four-drive systems. 
Drive 1.) 

6. Now all the non-system files will be converted and copied onto the 
destination diskette. As each file is copied, its name will be displayed. 

7. When the process is completed, you may remove the Model I diskette. It is 
unchanged by the convert program. The destination diskette contains the 
converted files. 

8. To restore password protection to the converted files, you may use the prot 
or attrib command. 
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ILOCK l fENDl command keys. The block end marker is inserted into text. 


Saving text to tape (SCRIPSIT tape version only) 

To do this: 1 vpe Ibis 


Type iBREAKl ffj] [ENTER! »*Dt J o’jl < >0* appears on the message line, 
ype a number to define the hyphenation range it h e smaller the number, the lighter 
le text will appear in the final document) and press [ENTERj 

. The cursor appears at the first hyphenation opportunity, at the last character in 
ie word where a hyphen may ocrur. 

. Move the cursor within the word to the place where you wish to hyphe nate Type 
hyphen (Q). If you do not wish to hyphenate the word. press [ENTER] . 

, The cursor will move to the next opportunity to hyphenate Repeal Step 7. 


Save document: (B REAK] [SliE NTER] 

Verify save: [B REAK 1 (3[ENTER! 

Loading Text 

Loading from disk (SCRIPSIT disk version only) 

In du this: I vpe this 

Load document: (BREAK ][l 1[~] id.* ument nam« i [ENTER ] 


At the end of the block the message HVPHI NATION COMPLf U appear on the RHoad document, 

lessage line and the cursor moves bark to the start of the hyphenation block. 

I»ad and < ham 


[Break] fti rEN TER] 

[BB EAK| [Tirrj!ET1id«w ument nam-‘ [ENTER! 


removing Hyphens 


Load from tape [BRE AK] [U][7][D IENTERi 


efore re-editing hyphenated text you should remove all hyphens. To do this. 

. Define the block if necessary. 

Type [BR EAKl TONfERl 

Answer the HOT /ONI message hy typing (J). 

When the cursor moves to the first hyphenation opportunity, press [CLEAR] . 

Requesting Document information 

ou mav ask SCRIPS!! the follow mg questions regarding vmir document: 
o do this Iy pc this 


Loading from tape (SCRIPSIT tape version only) 

To do this I \ pe this 

U»ad Horn men l [FEE Ag] [Ti l ENTE Rl 

Load and chain . [Bh EATEl fU][Tj[Ci rEN^TER1 

Printing Text 

Ihe hasir print command r [BR Eak"|(E][e NTE r] I here are ihrr»> 'switches n»*» 
a hie which instruct the computrr to do spenal things with th* printout these 
switches are appended to the pnnt command using commas For example 
[BRE AK) [Pj[T)rorn(E] - print formatted text to serial printer with pause between 
pages. Sw itches mav he appended in am order 


■ini line number of 
irsor 

rjnt length of docti 
ent in character. 

■int available memory 
characters 

riflt name of document 
memorv t SC It IPS! I* 
isk version only) 


( gRE*in m [El [ENTER] 

[BrJ aK] 0 [CLenter] 
[break{[?i^[e nterI 

[BBg Ak] [71[Fil[ENTERl 


To do ihis: 

Print to serial printer 
(through RS-212 inlrrfan i 

Pause between pages 
and w mi for paper 
to be Ted 

Print unformatted text with 
rommrnl lines and 
"invisible" characters 
showing. 

To halt a printout press 


Tvpe ibis 

[B BfA K] [Pi PH [Si lE NTE r] 
rBBTsiq[p]n[P][ ENiE_R3 

fB R EA k] B n m [enter! 


[CLEAR] 


7 


« 






























































u 

Disk BASIC 

Quick Instructions for Using Disk BASIC 

In this section we’ll “walk you’’ through the following procedures: 

1. Starting Disk basic 

2. Running a simple program 

3. Saving a program in a disk file 

4. Loading a program from a disk file 

For programming information, see the Disk basic section of this manual. 
Here we are showing procedures only. 

Starting Disk BASIC 

Under trsdos ready, type: BASIC (ENTER) 

The Computer will load and start basic. First, it will ask two questions. 
Press (ENTER) in response to each of them. 

HOW MANY FILES? (ENTER) 

MEMORY SIZE? (ENTER) 

A heading will be displayed, followed by: 

READY 

> 

You may now begin using Disk basic. 



Saving a Program 

You should have a program in memory, and be in basic’s ready mode. Type: 
SAVE "PROGRAM" (ENTER) 

basic should now save the program in a disk file we arbitrarily named 
“program.” Any other suitable file name would do. 


Loading a Program 

For this sample session, we will load the program just saved. 

First type: NEW (ENTER) to erase it from memory. (This is to prove that it can be 
retrieved from the disk file.) 
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TRS-80 MODEL III DISK SYSTEM 


Now type: LOAD "PROGRAM" (ENTER) and basic will load the specified 
program. 

You may now list it and run it. 

For further information on using Disk basic, see Section 3 of this manual. 

Setting the Cassette Baud Rate under Disk 
BASIC 

trsdos sets the cassette baud rate to High. If you would like to change this, use 
the following trsdos command: 

PATCH BASIC/CMD (ADD = 5202 >FIND=00 >CHG=FF) (ENTER) 

Consequently, you will be prompted with: CASS? whenever you start Disk 
BASIC. 

You may then type either H (High) or L (Low) to choose the rate you need. 

To change the system diskette back to its original state (i.e., no CASS?), simply 
use the trsdos patch command again but reverse the find and chg values. 
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OPERATION 


Troubleshooting and Maintenance 

If you have problems operating your Model 111 Disk System, please check the 
following symptoms and cures, and check the corresponding table in your 
Model III Manual, 

If you can’t solve the problem, take the unit to your local Radio Shack. We’ll 
have it fixed and returned to you as soon as possible. 


Symptom 

Cure 

Disk drive motors run 
continuously when the Computer 
is turned on. 

Check external drive connection sequence. 
Drive 26-1164 must always be the last 
external drive. 

Computer will not load trsdos. 

1. Make sure you have inserted the 
trsdos diskette properly in Drive 0. 

2. Make sure all peripherals are properly 
connected. 

Error Messages 

Look up the message in the trsdos or 
basic Error Message Section. The “cure” 
should be listed. 

Frequent disk i/o errors 

1. Diskette is partially erased. Backup the 
diskette, then re-format it. 

2. Diskette is worn out. Use backup copy, if 
available, to make a new working copy. 

3. Disk drives need cleaning or alignment 
by Radio Shack service technicians. 


Maintenance 

For reliable operation, the disk drives must be kept clean and properly aligned. 
These procedures should be done by Radio Shack service technicians, according 
to the following schedule: 


Degree of Use 

Commercial data processing 
environment 

Occasional home use 

Maintenance Interval 

Every month for medium use. 

Every 8-10 months; more often if 
needed. 


For further instructions, see the Troubleshooting and Maintenance section in 
your Model III Manual. 












TRS-80 MODEL III DISK SYSTEM 


Notation and Abbreviations 

For the sake of clarity and brevity, we’ve used some special notation and type 
styles in this book. 

capitals and punctuation 

indicate material which must be entered exactly as it appears. (The only 
punctuation symbols not entered are ellipses, explained below.) For example, 
in the line: 

DUMP LISTER (START = 7000,END = 7100,TRA = 7004) 

every letter and character should be typed as indicated. 

lowercase italics 

represent words, letters, characters or values you supply from a set of acceptable 
values for a particular command. For example, the line: 

LIST filename 

indicates that you can supply any valid file specification after list. 


Ellipsis indicates that the preceding items can be repeated. For example: 

ATTRIB filename (option,...) 

indicates that several options may be repeated inside the parentheses. 

■ 

This special symbol is used occasionally to indicate a blank-space character 
(ASCII code 32 decimal, 20 hexadecimal). 

PRINT “BHDIb!” 

X'nnrm' 

Indicates that nrum is a hexadecimal number. All other numbers in the text 
of this book are in decimal form, unless otherwise noted. 

X’7000’ 

indicates the hexadecimal value 7000 (decimal 28672 ). 

COMPUTER TYPE 

Any words, letters, or numbers that are displayed on the screen will be in 
computer type (dot-matrix). Uppercase letters are used; however, your screen at 
times may display lowercase letters instead. 
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OPERATION 


Specifications 

Diskettes 


Diskette Organization 
(Formatted Diskette) 


Operating Temperature 

Power Requirements 
(External Drives) 


514" mini-diskettes 
Radio Shack Catalog 
Number 26-305, 

26-405 (package of three), 
or 26-406 (package of 10) 

Single-sided 
Double-density 
40 Tracks 
18 Sectors/Track 
256 Bytes/Sector 

55 to 80 Degrees Fahrenheit 
13 to 27 Degrees Celsius 

120 VAC, 60 Hz, 28 VA (240 VAC, 50 
Hz, Australian; 220 VAC, 50 Hz, 
European) 











Description of TRSDOS 

What Is TRSDOS? 

trsdos (pronounced “triss-doss”) stands for “trs -80 Disk Operating System.” 
It fulfills three roles: 

1. Master Program 

2. Command Interpreter 
3 Program Manager 

As the master program, trsdos enables the microprocessor and its various 
components to interact efficiently. The components include! 

• Random Access Memory (ram), trsdos reserves space for its own needs and 
allocates space for user programs. 

• Disk Drives, trsdos interfaces with the disk hardware and provides a file 
system for storing system and user data on diskettes. 

*1 Input/output devices. These include the keyboard, video display, printer, and 
RS-232-C equipment. 

trsdos is also a command interpreter. Whenever it displays TRSDOS READY, 
you may enter commands that control how the system works. These are known 
as “library” commands. 

In its role as program manager, trsdos will load and run system or user 
programs. During this time, the system or user program is in control of the 
Computer. 

Figure 7 illustrates the relationships between these three roles. 


Where Does BASIC Fit In? 

Referring to Figure 7, you’ll see that Disk basic falls under the “language 
package” category. 

Disk basic consists of some general enhancements to Model III basic, plus the 
disk input/output capability. It uses Model III basic (stored in rom) whenever 
possible. For instance, the Model III basic rom includes all of the mathematical 
functions. 

If you’re used to the non-disk system, there’s one difference you should 
understand from the beginning: In the non-disk system, basic is in control when 
you start-up. In the disk system, however, trsdos is in control when you start¬ 
up, You have to tell trsdos to load and run basic. Only then can you begin 
running a program written in basic. 
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f s 


How TRSDOS Uses RAM 


trsdos is stored on the s 



Disk System. Each 


time the Computer is turned on or reset, the trsdos master program is loaded 
into ram so it can take charge. 



TRSDOS 


only a portion of that is in ram at once. This is possible because trsdos is 
divided into several independent “modules.” 

The “resident” module is in memory at all times. It consists of input/output 
drivers, tables, the command interpreter, and other essential routines. 

Additional modules are loaded as needed, and replaced (or “overlaid”) by other 
modules when they are no longer needed. 

Note: After you enter a library or utility command, you will usually hear 
trsdos accessing the system disk. It is loading an overlay module which 
contains the code necessary to complete the command. 

The Memory Map in Figure 8 illustrates how trsdos utilizes the available 
memory space. 


/-v 


f~S 
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Figure 8. trsdos Memory Map 
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Using TRSDOS 


Entering a Command 

Whenever the trsdos prompt, 

TRSDOS READ* 

is displayed, you can type in a command, which can be no more than 63 
characters in length. You must press (ENTER) to end the line, trsdos will then 
“accept” the command. 

For example, type: CLS (ENTER) trsdos will clear the Display and the trsdos 
ready prompt will reappear. 

In general, your commands will require more than one word. For example, to 
kill (delete) a file named myname, you have to specify the command and the 
filename. 

KILL MYNAME (ENTER) 

tells trsdos to find the file named myname, eliminate it from the diskette, and 
release the space previously occupied by that file. 

Whenever you type in a line, trsdos follows this procedure: 

1. First it checks to see if what you’ve typed is the name of a trsdos command. 
If it is, trsdos executes it immediately. 

2. If what you typed is not a trsdos command, then trsdos will check to see if 
it’s the name of a program file on one of the drives. 

3. When searching for a file, trsdos looks first through Drive 0, then Drive 1, 
etc., unless you include an particular drive specification with the file name 
— or specify the master command (see Library Commands). 

If trsdos finds a specified user file, it will load and execute the file if it is a 
program file. Otherwise, you’ll get an error message. 


Command Syntax 


Command syntax is a command’s general form (like the grammar or structure of 
an English sentence). The syntax tells how to use keywords (such as dir, list, 
create, etc.) together with the necessary parameters and punctuation. 

If you need help remembering the syntax form of a specific command while 
you’re operating trsdos, type in: 

HELP command TENTER) 
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command should be the specific Library Command you’re having trouble with. 
trsdos will give you the syntax format as well as a brief definition of the 
command. 


Commands (Syntax Forms) 

No-file commands 


command (options) comment 

options is a list one or more parameters that may be needed by the 
command. Some commands have no options. The parentheses 
around options must be included unless the option itself is 
omitted. 

comment is an optional field used to document the purpose of the 
command. Comments are useful inside automatic command 
input files (see build and do). 


One-file commands 


command filename (options) comment 

filename is a standard trsdos file specification. 
options— See definition above. 
comment —See definition above. 















Two-file commands 


command filename delimiter filename (options) comment 
filename is a standard thsdos file specification. 
delimiter is a blank space. 
options— See definition above. 
comment— See definition above. 


File Specification 

The only way to store information on a diskette is to put it in a disk file. 
Afterwards, that information can be retrieved via the file name you gave the file 
when you created or renamed it. 

A file specification has the general form: 


filename/ext. passwords 

filename consists of a letter followed by up to seven optional letters 
or numbers. 

/ext is an optional name-extension; ‘ext’ is a sequence of up to three 
letters or numbers, starting with a letter. 

.password is an optional password; ‘password’ is a sequence of up to 
eight letters or numbers, starting with a letter. 

:d is an optional disk-drive specification; ‘d’ is one of the digits 

0 , 1 , 2 , 3 . 


Note: There can be no blank spaces inside a file specification, trsdos 
terminates the file specification at the first blank space. 

For example: F ILEA/TXT .MANAGER:3 references the file named filea/txt 
with the password manager, on Drive 3. 
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The name, extension, and drive-specification all contribute to the uniqueness of 
a file specification. The password does not. It simply controls access to the file. 



File Names 

A file name consists of a name and an optional name extension. For the name, 
you can choose any letter, followed by up to seven additional numbers or letters. 
To use a name extension, start with a diagonal slash / and add no more than 
three numbers or letters; however, the first character must be a letter. 

For example: „ 

MODEL3/TXT INVENTORY DATA11/BAS 

NAMES/A12 AUGUST/A 15 WAREHOUS 

TEST TEST1 TESTI/A 

are all valid and distinct file names. 

Although name extensions are optional, they are useful for identifying what type 
of data is in the file. For example, you might want to use the following set of 
extensions; 

, /BAS for basic program 

/TXT for ascii text 

/CMD for machine-language cofnmand file 

/DA*T for data 

One advantage of using extensions is that you can tell by just looking at the 
directory what kind of information a file contains. 

Another advantage is that trsdos can recognize certain extensions. For 
example, if a file has the extension /cmd, the trsdos will load and attempt to 
execute that file when you type: filename (ENTER) omitting the extension /cmd. 


Drive Specification 

If you give trsdos a command such as: KILL TEST/A trsdos will search for 
the file test/a first in Drive 0, then in Drive 1, 2, and finally in Drive 3 until it 
finds the file. 

Anytime you omit a drive-specification, trsdos will follow this sequence, 
unless you use the master command. 

It is possible to tell trsdos exactly which drive you want to use by specifying 
the drive. A drive specification consists of a colon followed by one of the digits 
0,1,2, or 3, corresponding to one of the four drives you might be using. 

For example: KILL TEST/A: 3 tells trsdos delete the file test/a on Drive 3 
only. 
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Anytime trsdos has to open a file (e.g., to list it for you), it will follow the 
same sequence. When trsdos has to write a file, it will skip over any write- 
protected diskettes. 

Password 

You can protect a file from unauthorized access and use by assigning passwords 
to the file. That way, a person cannot gain access to a file without using the 
appropriate password. 

It ? s important to realize that every file has a password, even if you didn’t specify 
it when the file was created. In such instances, the password becomes eight 
blank spaces: In this case, the file becomes unprotected — anyone can gain total 
access simply by referring to the filename. 

trsdos allows you to assign two passwords to a file: 

• An “Update word,” which grants total access to the information 

• An ' Access word,” which grants limited access to the information (see 
attrib) 

When you create a file, the Update and Access words are both set equal to the 
password you specify. You can change them later with the attrib command. 

A password consists of a period followed by one to eight letters or numbers. If 
you do not assign a password to a file, trsdos uses a default password of eight 
blanks. 

For example, suppose you have a file named secret/bas. and the file has 
myname as an update and access word. Then the command: KILL SECRETS/ 
BAS will not cause the file to be killed. You must include the password myname 
in the file specification. 

Suppose a file is named domain/bas and has blanks for the password. Then the 
command: KILL DOMAIN/BAS.GUESS will not be obeyed, since guess is not 
the password. 

A Few Important Definitions 

System vs. Data Diskettes 

A system diskette is one which contains the trsdos disk operating system 
software. Subject to space limitations, it may also contain your own files. A 
system diskette must always be in Drive 0 while the Computer is in use. 

A data diskette, on the other hand, does not contain the operating system 
software, and therefore cannot be used in Drive 0. It may be used in Drive 1, 2 
or 3. Such a diskette has a maximum of space available for storing your own 
programs and data. 
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System, Program, and Data Files 

System files include the trsdos operating system software, the basic language 
interpreter, the format, backup and convert utilities, and other software 
which is released by Radio Shack. These files appear in the Directory with an 
“S” attribute. (See dir) 

Program files are stored in a special format which allows them to be loaded and 
executed directly from the trsdos ready level. For example, the basic 
interpreter is a program file. 

Data files include all files that are not in the correct format to allow loading and 
executing from trsdos ready. For example, a program written in basic will be 
stored as a data file. It can be loaded and executed from basic, but not from 

TRSDOS READY. 

Master Passwords 

Each diskette is initially assigned a master password during format or backup. 
(Your master password for trsdos is password.) The master password allows 
you to use backup, purge, and prot on a diskette. Using a diskette’s master 
password, you may change it (see prot). 
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TRSDOS Library Commands 

APPEND 


Append files 


append source-file destination-file 

source-fiie is the specification for the file which is to be 
copied onto the end of the other file. 

destination-file is the specification for the file which is to 
receive the appendage (addition). 


OPnoAi a ; c fusers nur 


Note: Both source- and destination-files must be in ascii 
format (data files or basic programs saved with the a 
option). 





append copies the contents of the source-file onto the end of the destination-file. 
The source-file is unaffected, while the destination-file is extended to include the 
source-file. 

Note: The logical record lengths must match. See dir for more information on 
logical record lengths. HH 

Examples 

APPEND WQRDFILE/C WORDFILE/D 
A copy of wordfile/c is appended to wordfile/d. 

APPEND REGI0N1/DAT TOTAL/DAT,GUESS 

A copy of region 1 /dat is appended to total/dat, which is protected with the 
password guess. 


Sample Uses 

Suppose you have two data files, payrolua and payroll/b. 













PAYROLL/ft 

Atkins# N * R ♦ ♦♦♦«««♦ 

Baker# J * B * «*«***«» 

Chambe rs # C* P* * * * * ♦ 
Dodson# M*N* * * * * * ♦ ♦ 

Kickamon# T*Y* * * ♦ ♦ * 



PAYROLL/B 

Lewis # G * E * ******** 

Miller# L♦0♦ ******* 

Peterson# B« ******* 

Rodrisfuez# F.. 


You can combine the two files with the command: 


APPEND PAYROLL/B PAYROLL/A 
payroll/a will now look like this: 


PAYROLL/A 

Atkins# W 4 R♦ 444444* 

Baker# J*B* 44*444*4 
Chambers# C * P * * * * * * 

Dodson# M * W.. 

Kickamon# T * Y * ***** 

Lewis# G * E * *44*4*4* 

Miller# L * 0 * * * * * * * * 

Peterson# B* ******* 

Rodriguez# F * * * * * * * 

payroll/b will be unaffected. To see the APPENDed file, type LIST PAYROLL/A 
(ASCII). 

Note: Do not load a program under basic after an append, p 


ATTRIB 

Change a File’s Password 


attrib file (visibility, acc = name, upo = name, prot= level) 

file is the file specification. 

visibility must be i or n. Tells trsdos whether the file is Invisible (i) or 
Non-invisible (n) (see dir). If omitted, visibility is unchanged. 

acc = name tells trsdos the access word. If omitted, the access word 
is unchanged. If acc =, is used, the access word is set to 
blanks. 

upd= name tells trsdos the update word. If omitted, the update word 
is unchanged. If upd =, is used, the update word is set to 
blanks. 
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prot= level tells trsdos the protection level for access. If omitted, 
level is unchanged. 


Level Degree of access granted by access word 

full Full access, no protection. 

kill Kill, rename, read, execute, and write (gives 

total access, i.e., the least-protected). 

name Rename, read, execute, and write. 

write Read, execute, and write. 

read Read and execute. 

exec Execute only. 


Note: Each level allows access to itself plus all lower levels. 



attrib lets you change the passwords to an existing file or makes the file 
invisible or non-invisible. Passwords are initially assigned when the file is 
created. At that time, the update and access words are set to the same value 
(either the password you specified or a blank password). 


Examples 


ATTRIB DATAFILE (I »ACC = JULYld »UPD=M0USE .PRQT=READ), 

Makes the file invisible, sets the access password to julyh and the update 
password to mouse. Use of the access word will allow only reading and 
executing the file. 


ATTRIB PAYROLL/BAS.SECRET (N>ACC=») 

Sets the access word to blanks. The file is made non-invisible and the protection 
level assigned to the update word is left unchanged. 


ATTRIB OLD/DAT.APPLES (UPD=») 
Sets the update word to blanks. 


ATTRIB PAYROLL/BAS,PW (PRGT=EXEC) 

Leaves the access and update words unchanged, but changes the level of access. 


Sample Uses 


Suppose you have a data file, payroll, and you want an employee to use the 
file in preparing paychecks. You want the employee to be able to read the file 
but not to change it. Then use a command like: 
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ATTRIB PAYROLL (I>ACC = PAYDAY »UPD = AMOCADO >PR0T=READ) 

Now tell the clerk to use the password payday (which allows read only;; while 
only you know the password, avocado, which grants total access to the file. 

Protecting BASIC Programs 

You may give a basic program execute-only protection using the attrib 
command. For example, suppose the program is named test (no password). 
Under trsdos ready, execute this command: 

ATTRIB TEST (ACC= >UPD=VALLEY »PR0T=EXEC) 

Now test has a blank access password, an update password of valley, and an 
access level of execute only. Without using the update password, there is now 
only one way to execute the program: 

1. Start basic. 

2. Type: RUN "TEST 1 ' 

(This is the only way to access the program. If the operator attempts to load 
it instead, basic will erase the program from memory before returning with 

READY. 9 

After the run “test” command, basic will load and execute the program. If 
the operator presses (BREAK) or if the program ends normally, basic will erase the 
program before returning with the ready message. This makes it impossible to 
obtain a listing of the program— unless the update password is used . 

Of course, if you use the update password, you may gain full access to the 
program. 


AUTO 

Automatic Command after System Start-up 


auto command-line 

command-line gives trsdos a command or the name of an executable 
program file created by build. 

if command-line is given, the command will be executed on reset/ 
power-up. 

if command-line is omitted, the previous auto command is erased 
from the diskette. 
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This command lets you provide a command to be executed whenever trsdos is 
started (power-up or reset). You can use it to get a desired program running 
without any operator action required, except for typing in the date and time. 

When you enter an auto command, trsdos writes command-line into its start¬ 
up procedure, trsdos does not check for valid commands; if the command line 
contains an error, it will be detected the next time the System is started up. 

Examples 

AUTO DIR (SYS) 

Tells trsdos to execute the command dir (sys) after the start-up procedure. 

Each time the System is reset or powered up, it will automatically execute that 
command after you enter the date and time. 

AUTO BASIC 

Tells trsdos to load and execute basic each time the System is started up. 

AUTO FORMS (WIDTH= 80 ) 

Tells trsdos to reset the printer width parameter each time the System is started 
up. 

AUTO PAYROLL/CMD 

Tells trsdos to load and execute payroll/cmd (must be a machine-language 
program) after each System start-up. 

AUTO DO STARTER 

Tells trsdos to take automatic key-ins from the file named starter after each 
System start-up. See build and do. 

To Erase an AUTO Command 

Type: AUTO (ENTEH) 

This tells trsdos to erase any automatic command. The command will be 
deleted the next time you power-up or reset the System. 

The acknowledgement: AUTO = "" is displayed after an erasure. 

To Override an AUTO Command 

You can bypass any automatic command by holding down (ENTER) while pressing 
reset. You must continue holding down (ENTER) until you are prompted for the 
date during the initialization process. 












BUILD 

Create an Automatic Command Input File 


build file 

file is a file specification which cannot include an extension. 


This command lets you create an automatic command input file which can be 
executed via the do command. The file must contain data that would normally 
be typed in from the keyboard to the trsdos ready mode. 

build files are intended for passing command lines to trsdos just as if they’d 
been typed in at the trsdos ready level. Note: clear cannot be used in a do 

O 

When you enter the build command, build creates the file and immediately 
prompts you to begin inserting lines. Each time you complete a line, press 
(ENTER) . (While typing in a line, you can use the usual cursor control keys for 
erasures and corrections.) 

To end the build file, simply press (BREAK) at the beginning of a line. 

First type: BUILD filename 

You will then be prompted to type in the command text. You then type in up to 
63 characters, then press (ENTER) . You may enter as many lines as necessary. 
Press (BREAK) to quit and return to trsdos ready. 

A Sample BUILD-File 

Here’s a hypothetical BUiLD-file that initializes the serial interface and the printer 
driver: 

SETCOM <BAUD=1200tWAIT) 

FORMS (WIDTH=80) 

PAUSE SERIAL INTERFACE B. PRINTER INITIALIZED 

• 
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CLEAR 

Clear User Memory 



CLEAR (START = 3333 ,END = bbbb ,MEM = CCCC) 

start=3333 tells trsdos where to start clearing user memory, aaaa 
is a four-digit hexadecimal number from 6000 to the end of user 
memory. If this option is omitted, 6000 is used. If this option is 
used, end = bbbb must also be used. 

end = bbbb tells trsdos to clear user memory to a specified end. bbbb 
is a four-digit hexadecimal number no less than the start 
number and no greater than the top of memory. If this option is 
used, start=3333 must also be used. 

mem = cccc sets the memory protect address, cccc is a four-digit 
hexadecimal number from oooo to ffff. If this option is omitted, 
the memory protect address is reset to end of user ram. 

If all options are omitted, all available ram is cleared, memory- 
protect is reset to end of memory, the Display is cleared, all i/o 
drivers are reset (see Memory Requirements of trsdos). 



This command gets you off to a fresh start. 

Depending on the options you select, this command will: 

• Zero user memory (load binary zero into each memory address above 6000) 

• Clear the Display 

• Un-protect all memory 

See Memory Requirements of trsdos for more information on the memory- 
protect address. Note: clear cannot be used in a do file. 

Example 

CLEAR (START=9000»END=0A000) 

Note: Hexadecimal numbers which begin with a letter must be prefaced by zero 
(see above example). 

CLEAR (MEM=7000) 


r\ 
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CLOCK 

T\irn On Clock Display 


CLOCK ( switch ) 

switch gives trsdos one of two options, on or off. 
If option is omitted, trsdos uses on. 


This command controls the real-time clock display in the upper right corner of 
the Video Display. When it is on, the 24-hour time will be displayed and 
updated once each second, regardless of what program is executing. 

Clock display is off at trsdos start-up. 

Note: Except during cassette and disk i/o, the real-time clock is always running, 
regardless of whether the clock display is on. 

Examples 

CLOCK 

Turns on the clock display. 

CLOCK (OFF) 

Turns the clock display off. 

See time and date. 


CLS 

Clear the Screen 


CLS 


This command clears the Display and puts it in the 64 character/line mode. 

Example 

CLS 
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COPY 

Copy a File or Files 


Three forms: 

A) copy source-file destination-file 

source-file is a file specification for the file to be copied. 

destination-file is a file specification for the name and drive of the 
duplicate file. 

B) copy source-file :d 

source-file is defined above. 

:d tells trsdos to copy the file onto drive d, using the same file name. 

C) copy /ext :d 

text is a “wild-card’’ file specification in which the file name is 
omitted and the extension is given, trsdos will copy all files 
which have a matching extension, regardless of the file name. 

:d is defined above. 


This command copies source-file into the new file defined by destination-file. 
This allows you to copy a file from one disk to another, using a single drive if 
necessary. (In the latter case, you must include drive specifications in both file 
specifications.) For single-drive systems (Drive 0), both diskettes must contain 
trsdos. (i.e., Data diskettes aren’t allowed in Drive 0.) 

Examples 

COPY OLDFILE/BAS NEWFILE/BAS 

Copies oldfile/bas into a new file named newfile/bas. trsdos will search 
through all drives for oldfile/bas, and will copy it onto the first disk which is 
not write-protected. 

COPY NAMEFILE/TXT :1 

This command specifies a file named namefile/txt to another disk.* 

COPY FILE/EXT:0 :1 

This command copies file/ext from Drive 0 to Drive 1. 
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COPY /BAS:0 :1 

tells trsdos to copy all Drive 0 files which have the extension /bas. The files 
will be copied onto Drive 1, using their present file names and extensions. 


Sample Use 

Whenever a file is updated, use copy to make a backup file on another disk. You 
can also use copy to restructure a file for faster access. Be sure the destination 
disk is already less segmented than the source disk; otherwise the new file could 
be more segmented than the old one. (See free for information on file 
segmentation.) 

To rename a file on the same disk, use rename, not copy. 


CREATE 

Create a Pre-allocated File 


create filename (lrl = aaa, rec = bbb) 
filename is the file specification. 

lrl = aaa is the logical record length, aaa is a decimal number 
between zero and 255. If omitted, 256 is assumed. 

rec = bbb is the number of records to allow for. bbb is the number of 
records desired. If omitted, no records are allocated. 


This command lets you create a file and pre-allocate (set aside) space for its 
future contents. This is different from the default (normal) trsdos procedure in 
which space is allocated to a file dynamically, i.e., as necessary when data is 
written into the file. 

If you open the file for sequential writes, trsdos will de-allocate (recover) any 
unused granules when the file is closed. If you open the file for random access, 
trsdos will not de-allocate space when the file is closed. 
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You may want to use create to prepare a file which will contain a known 
amount of data. This will usually speed up file write operations. File reading 
will also be faster, since pre-allocated files are less segmented or dispersed on 
the disk — requiring less motion of the read/write mechanism to locate the 
records. 

Examples 

CREATE DATAFILE/BAS <REC=300, LRL=0) 

Creates a file named datafile/bas, and allocates space for 300 256-byte 
records. 

CREATE NAMES/TXT.IRIS (LRL=G4 *REC=50) 

Creates a file named names/txt protected by the password iris. The file will be 
large enough to contain 50 records, each 64 bytes long. 

CREATE PAYROLL/BAS 

Creates a file named payroll/bas but allocates no space to it. 

Sample Use 

Suppose you are going to store personnel information on no more than 250 
employees, and each data record will look like this: 

Name (Up to 25 letters) 

Social Security Number (11 characters) 

Job Description (Up to 92 characters) 

Then your records would need to be 25 + 11 + 92 = 128 bytes long. 

You could create an appropriate file with this command: 

CREATE PERSONNL/TXT (REC = 250 tLRL=128) 

Once created, this pre-allocated file would allow faster writing than would a 
dynamically allocated file, since trsdos would not have to stop writing 
periodically to allocate more space (unless you exceed the pre-allocated 
amount). 



DATE 

Reset or Get Today’s Date 


date mm/dd/yy 

mm/dd/yy \% the specification for the month (mm), day (dd) and 

year [yy]. 
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Each must be a two-digit decimal number between the following 
ranges: 

mm 01-12 
dd 00-31 
yy 00-99 

The specifications are an option; however, if one specification is 
used, they all must be used. 

If mm/dd/yy is omitted, trsdos displays the current date. 

If mm/dd/yy is given, trsdos resets the date. 


This command lets you reset the date or display the date. 

You initially set the date when trsdos is started up. After that, trsdos updates 
the date automatically, using its built-in calendar. You can enter any two-digit 
year after 1900. 

When you request the date, trsdos displays it in the format: 07/25/80 for July 
25, 1980. 

Examples 

DATE 

Displays the current date. 

DATE 07/18/80 

Resets the date to July 18, 1980. 


DEBUG 

Start Debug Monitor 




This command starts the debug monitor, which allows you to enter, test, and. 
debug machine-language programs. 
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Its features include: 

• Full- or half-screen displays of memory contents 

• Commands for modifications to ram and register contents 

• Single-step execution of programs 

• Breakpoint interruption of program execution 

• Transfer of control (Jump) 

• “Editing” of disk-files 

debug uses the memory area from X’4E00’ to X’54FF’ (see trsdos Memory 
Map), debug can only be used on programs in the user area x’5500' to top. 


Examples 

DE6UG 

Turns debug on. Press ® to quit debugging and return to trsdos. 

0 

Turns debug off. 

Command Description 

Debug commands are usually entered by pressing a single key. In most cases, 
you do not have to press (ENTER) after the command has been typed in. Either 
a prompt will immediately be displayed or debug will execute the operation 
without further instruction. 

In some cases, you will have to enter a specific hexadecimal value or address 
(see R and j commands, for instance). Instead of pressing (ENTER) after the 
address is typed in, you will have to press (SPACEBAR ). 

Once you have entered the debug program, you may use any of the following 
special commands: 


D (Display Memory Contents) 

Press (D) to display the contents of memory, trsdos will respond with the 
prompt: D ADDRESS = You should type in the hexadecimal address of the 
memory location you wish to see. 

The display will be either half- or full-screen, depending on the format you are 
currently using (see below). 
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X (Half-Screen Display) 

Press ® to put the Display in the half-screen format. A 128-byte block of 
memory will be displayed starting with the next lowest address which is a factor 
of 16. 

Figure 9 shows a typical half-screen format. 

S (Full-Screen Display) 

Press © to display the contents of a 256-byte block of memory starting with the 
next lowest address which is a factor of 256. 

Note: The last 16 bytes on the Display will be overlaid by any command line 
typed in after the full-screen display is updated. 

M (Modify RAM) 

Press ® to change to the disk utility display format (see the F command). 
trsdos will respond with the prompt: M ADDRESS = You should type in the 
four-digit hexadecimal address of the memory location you wish to modify, 
followed by a blank space (anything other than a space will abort the 
command). 

The display will change to the memory edit format. The cursor will appear as a 
blinking character at the specified location. 

To exit the modify mode, press (ENTER) to keep all changes made. 

R (Change Register Contents) 

Type: 


n aa.bbbb (spacebar) 

aa is the name of one of the register pairs af, bc, de, hc, or pc. 

bbbb is the four-digit hexadecimal value which will be loaded into aa. 
If fewer than four digits are typed in before pressing (spacebar) . 
leading zeros are assumed. 


I (Instruction Single-Step) 

Pressing © will allow the Computer to execute a single z-80 instruction. The 
display will then be updated. 
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Start address 


RAM display— 


ASCII display 



s Z -80 register contents J 
Op-code Instructions at the “PC” address 


Figure 9. Half-Screen Format. 


The instruction in the memory contents referenced by the program counter is 
executed. The program counter is increased by the appropriate value, and the 
control is returned to debug. 

debug will not, however, step through a call or jump into a rom address. 


C (Call Single-Step) 

If you wish to complete an entire call/return sequence, press ®. The call is 
then executed and control is returned to debug when the subroutine returns. 
Otherwise, this instruction acts just like the i command. 

You will not be able to step through a call or jump into a rom address. 

U (Update) 

Pressing (U) causes the Display to be updated repeatedly. Press any key to exit 
from this mode. 
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; (Increment Display Address) 

If the Display is half-screen, the first location shown is incremented by 16 when 
you press (T). If the full-screen format is displayed, the starting address will be 
incremented by 256. 

— (Decrement Display Address) 

If the Display is half-screen, the first location is decremented by 16 when you 
press (ED- If the full-screen format is displayed, the starting address will be 
decremented by 256. 

J (Jump) 

Press (D to transfer control to a machine-language program, setting optional 
breakpoints. 

Debug will respond with the prompt: J ADDRESS? = 

You may type in a jump address and a breakpoint address. The command is 
terminated when you press (ENTER) . Type in the addresses in one of three 
formats: 


j address? = aaaa.bbbb (ENTER) 
j address? = aaaa (enter) 

J ADDRESS? = ,bbbb (ENTER) 

aaaa is a four-digit hexadecimal address specifying the jump 

destination, if omitted, the address in the pc register is used. 

bbbb is a four-digit hexadecimal address specifying a breakpoint. 
Before the Computer executes an instruction at this address, it 
will return control to debug. If this address is omitted, control 
will not return to debug. 


Notes: Breakpoints must be set at the beginning of z-80 instructions. You may 
not set breakpoints in rom addresses. The breakpointed address will contain an 
x’F7’ until the breakpoint is encountered. Then the original contents will be 
restored and debug will take control again. 


Q (Quit) 

Pressing (2) turns off debug and returns control to trsdos. 
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F (File Patch Utility) 

This command lets you load and modify the contents of a diskette file. 

When you press ®, debug will respond with the prompt: FILESPEC?. Enter the 
name of the file to be patched. 

debug will set up a full-screen display showing the first 256 bytes in the file. 

You can “page” through the file using the CD and © keys. 

Figure 10 gives a typical display. 

In this file-display mode, both hexadecimal and ascii are given for each byte. If 
a code has no displayable character, a period is shown in the ascii area. 

The display control commands are like those for the normal file-display mode: 

CD Next page 
© Previous page 

To change the file contents, press ®. This puts you in a modify-memory mode 
like the one previously described. Use the arrow keys to position the cursor (a 
blinking character), then type in the correct contents as a hexadecimal value. 
When you are through changing a page on the display, press (ENTER) . The 
diskette file will be updated and you will be returned to the file-display mode. 

To cancel changes made, do not press (ENTER) , press (BREAK) . This will put you 
back in the file-display mode without updating the diskette file. You may press 
CD then ©) to restore the page display to its actual contents. 

To quit patching a file, press (BREAK) while in the file display mode, debug will 
prompt you for a new file specification. Press (BREAK) again and you will be 
returned to trsdos ready. 
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Figure 10. Full-Screen Format 
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DIR 

List the Diskette Directory 


DIR :d(lNV,SYS,PRT) 

:d is the desired drive directory. If omitted. Drive 0 is assumed. 

inv lists the invisible user files. If omitted, non-invisible user files are 
listed. 

sys lists system and user files. If omitted, only non-invisible user files are 
listed. 

prt lists the directory to the Printer. If omitted, the directory will be listed 
on the Video Display only. 

If no option is given, trsdos lists non-invisible user files in Drive 0. 


This command gives you information about a disk and the files it contains. 

To pause the listing, press f@~) . To continue, press (ENTER) . To terminate the 
listing, press (BREAK) . 

Examples 

DIR 

Displays the directory of non-invisible user files in Drive 0. 

DIR :1 (PRT) 

Lists the directory of the user files in Drive 1 to the Printer. 

Sample Directory Listing 

(See Figure 11.) 

Definition of column headings 


® File Name — The name and extension assigned to a file when it was'created. 
The password (if any) is not shown. 

© Attributes-—A four-character field. 

The first character is either i (Invisible) or n (Non-invisible). 

The second character is s (System) or * (User) file. 

The third character gives the password protection status: 
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Figure 11. Directory Listing. 

x The file is unprotected (no password). 
a The file has an access word but no update word, 
u The file has an update word but no access word. 
b The file has both update and access words. 

The fourth character specifies the level of access assigned to the access word: 
0 Total access 

1 Kill file and everything listed below. 

2 Rename file and everything listed below. 

3 This designation is not used. 

4 Write and everything listed below. 

5 Read and everything listed below. 

6 Execute only. 

7 No access. 

(D Number of Free Granules — How many free granules remain on the diskette. 

© Logical Record Length — Assigned when the file was created. 

© Number of Records—How many logical records have been written. 

© Number of Granules — How many granules have been used in that 
particular file. 
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® Number of Extents — How many segments (contiguous blocks of up to 32 
granules) of disk space are allocated to the file. 

© End of File (eof) — Shows the last byte number of the file. 

© Creation Date — When the file was created. 



DO 

Begin Auto Command Input from a BUILD-File 


do command-line 

command-line is the name of file created with build. No extension should 
be specified. The file will automatically be given the extension /bld. 


This command reads and executes the lines stored in a special-format file 
created with the build command. The System executes the commands just as if 
they had been typed in from the Keyboard. 

Command lines in a build file may include library commands or file 
specifications for user programs. 

When do reaches the end of the automatic command input file, it returns control 
to TRSDOS. 

The debug and clear command cannot be included in a build file. 

In addition to executing trsdos library commands, you can load and execute 
user programs from a DO-file. You will probably want to make your program 
name be the last line in the DO-file. 


Examples 

DO STARTER 

trsdos will begin automatic command input from starter, after the operator 
answers the Date and Time prompts. 

AUTO DO STARTER 


Whenever you start trsdos, it will begin automatic command input 
from STARTER. 



46 









TRSDOS 



Sample Uses 

Suppose you want to set up the following trsdos functions automatically 
on start-up: 

FORMS (WIDTH=B0) 

CLOCK (ON) 

Then use build to create such a file. If you called it begin, then use the 
command: AUTO DO BEGIN to perform the commands each time trsdos 
starts up. 


DUAL 


Duplicate Output to Video and Printer 


OUAL ( switch ) 

switch is one of two options, on or off. If omitted, trsdos uses on. 



This command duplicates all video output to the Printer, and vice versa. It takes 
effect immediately. 

Notes: 

1. Video and printer output may be different because of intrinsic differences 
between output devices and output software. 

2. Using the dual command will slow down the video output process. 

3. The dual command cannot be used during route and vice versa. 

4. The printer should be ready when you execute the command. 

Sample Use 

For a printed copy of all system/operator dialog, type: DUAL (ENTER) 

To turn off the dual process, type: DUAL (OFF) (ENTER) 
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DUMP 

Store a Program Into a Disk File 



DUMP file (START = 3333,END = bbbb, TRA = CCCC.RELO = dddd) 

file is the file specification 

start = 3333 is the start address of memory block, aaaa must be a four¬ 
digit hexadecimal number greater than or equal to X7ooo.’ 

end = bbbb is the end address of the memory block, bbbb must be a four¬ 
digit hexadecimal number. 

tra = cccc is the transfer address where execution starts when the program 
is loaded, cccc must be a four-digit hexadecimal number. If this 
option is omitted, the command will default to trsdos re-entry. 

relo = dddd is the start address for relocating or loading the program back 
into memory, dddd must be a four-digit hexadecimal number. If this 
option is omitted, no relocation will take place. 

Note: Addresses must be hexadecimal form, without the X' • notation. 
You must add the prefix “0” to any hex number which begins with a 
letter. 


This command copies a machine-language program from memory into a 
program file. You can then load and execute the program at any time by entering 
the file name in the trsdos ready mode. 

Examples 

DUMP LISTER (START=7000»END=7100*TRA=7004) 

Creates a program file named lister/cmd containing the program in memory 
locations X’7000’ to x’7ioo\ When loaded, lister/cmd will occupy the same 
addresses, and trsdos will protect memory beginning at x - 7000\ The program is 
executable for the trsdos ready mode. 

DUMP PR0G2 (START = 7000tEND = 7F00»TRA = 8010 >RELO=8000) 

Creates a program file named prog2/cmd containing the program in addresses 
X'7000’ to X‘7Foo\ When loaded, PROG2/CMD will reside from X'sooo’ to x sfoo’. 

Execution will start at x’soio’. 

rs 
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ERROR 

Display Error Message 


error number 

number is a decimal number for a trsdos error code. 


This command displays a descriptive error message. For example, after 
receiving the message, * * ERROR 47 * * you may respond with the 
command: ERROR 47 (ENTER) and trsdos will display the full error message. 

For a complete list of error codes and messages, see the Technical Information 
section of this manual. 


FORMS 

Set Printer Parameters 


FORMS (WIDTH = W , LINES = /) 

width = w is the maximum number of characters per output line. If a line 
reaches this length, trsdos will insert a carriage return to force a new 
line. If this option is omitted, the current maximum width will be 
used. To disable the maximum line width feature, use width =255. 
trsdos will not force new lines. 

lines = / is the number of lines per page, trsdos does not use this value. 
However, basic will use it in computing the necessary page 
displacement for execution or if lprint chr$(12) is executed. If lines=/ 
is omitted, the current value is used. 


This command lets you modify the printer forms control features of trsdos. 
The default values are: 

Maximum line width: 132 
Lines/page: 60 

forms also sets the line count to 0. 
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Examples 

If you are using 8 1 / 2 , '-wide forms, you will probably want to set width = 80: 
FORMS (WIDTH=80) 

If you are using 14"-long forms, you may want to set lines = 78. 

FORMS (LINES=78) 

This change will allow the basic statement, lprintchr$(12), to advance a page 
by the correct number of lines. 

Notes: 

1. The width you specify is stored in ram location 16427. The lines you 
specify is stored in ram location 16424. 

2. The Printer must be ready when you execute this command. 

FREE 

Display Disk Allocation Map 


FREE :</(PRT) 

:d is the drive specification. If omitted, Drive 0 is used. 

(pRT) tells trsdos to send the map to the Printer. 

If omitted, trsdos sends the map to the Video Display only. 


This command gives you a map of granule allocation on a diskette. (A granule, 
1280 bytes, is the unit of space allocation.) It also shows the location of the 
directory and any flawed sectors. 

When a diskette has been used extensively (file updates, files killed, extended, 
etc.), files often become segmented (dispersed or fragmented). This slows the 
access time, since the disk read/write mechanism must move back and forth 
across the diskette to read and write to a file. 

free helps you determine just how segmented your disk files are. If you decide 
you’d like to re-organize a particular file to allow faster access, you can then 
copy it onto a relatively “clean” diskette. 
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Examples 

FREE 

Displays a free space map of the diskette in Drive 0. 

FREE (PRT) 

Lists the free space for Drive 0 to the Printer. 

FREE :1 (PRT) 

Lists the Drive 1 map to the Printer. 

A Topical FREE Display 

Four special symbols are used in the free map. 

• Unused Granule 

Direct Directory Information 

X Allocated Granule 

Flawed Granule Contains a Flawed Sector (Unusable) 

A typical free map display is shown in Figure 12. 



Disk Name 


All six granules in 
track 2 are allocated 


// Fr« Sp^ce 

TRSDOS -—-“gS 2 - 

KXXXXK c XXXXXX i xxxxxx ; J 
mxxk * xxvxtfx ; xxxxxx ? i 


-- Drive* 0 

xscx>:x>r ; xxmx * xxxxxx 

XXXXXX : X. : - P • 


T r k B 

aei-oA ? 
05-09 i 

20-24 1 
25-29? 
30-34* 
35-39= 


XXXXXX : XXXXXX * Direct 5 XXXXXX 
XXXXXX t XXXX.. - 


X.XXXXX 


Figure 12. Free Map. 


The directory is located 
on track 17. 


HELP 

Explanation of TRSDOS Command 


help command 

command is the specific trsdos command or subject on which you need 
help. If omitted or if an invalid subject is given, trsdos will list all 
available subjects. 
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Example 

If you type in the following: HELP BACKUP (ENTER! trsdos will respond with 
the syntax format, a definition of the command, and an explanation of 
the abbreviation. 

HELP SYNTAX tells trsdos to explain the help descriptions. 


KILL 


Delete a File or Group of Files 


Two syntaxes: 

A) kill file 

file is a file specification 

B) kill lext:d 

/ext is a file extension that must contain three characters. 
:</ is a drive specification. It must be provided. 


This command deletes one file or a group of files, depending on which form is 
used. Form A deletes the specified file. If no drive specification is given, 
trsdos deletes the file from the first diskette that contains it. 

Form B deletes all files with a specified extension, regardless of the file name of 
each file. If no drive specification is given, the files will be deleted from the first 
drive that contains a matching file specification. 

Examples 

KILL TESTPRQG/BAS 

Deletes the named file from the first drive that contains it. 

KILL JOBFILE/IDY♦PASSWORDs1 

Deletes the named file from Drive I. The file has a password of password. 

KILL /BAS:0 

Deletes from Drive 0 all files having the extension /bas. 
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LIB 

Display Library Commands 


LIB 


This command lists to the Display all the library commands. For help with a 
command, use help. 

Example 

LIB 

LIST 

List Contents of a File 


LIST file (PRT,SLOW,ASCII) 

file is the tile specification. 

prt tells trsdos to list to the Printer. If omitted, only the Video Display is 
used. 

slow tells trsdos to pause briefly after each record. If omitted, the listing is 
continuous. 

ascii tells trsdos to list the file in ascii format. If omitted, hexadecimal 
format is used. 


This routine lists the contents of a file. The listing shows both the hexadecimal 
contents and the ascii characters corresponding to each value. For values 
outside the range (X’2o\ X’7F’>, a period is displayed. 

Use the ascii option for text files and basic programs saved with the a option. 

Note: Only ascii codes x oo’-x’7F’ are sent to the Printer. Bit 7 is always 
set to 0. 


During the listing, press CUD to pause, CENTER) to continue, or (BREAK) to exit. 
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Examples 

LIST DATA/TXT (ASCII) 

Lists the contents of data/txt in ascii format. 

LIST FILE/A (SLOW) 

Lists the contents of file/a, pausing after each record. 
LIST PROGRAM/CMD (PRT) 

Lists the file program/cmd to the Printer. 



LOAD 

Load a Program File 


LOAD file 

file is a file specification for a file created by the dump command. 




This command loads a machine-language program file into memory. After the 
file is loaded, trsdos returns to the trsdos ready mode. 

You cannot use this command to load a basic program or any file created by 
basic. See the basic Reference Manual for instructions on loading basic 
programs. 

Note: The file must load into the user area <x'7<xx)‘-top). 

Examples 

LOAD PAYROLL/FT1 

Sample Use 

Often several program modules must be loaded into memory for use by a master 
program. For example, suppose payroll/pti and payroll/pt2 are modules, and 
menu is the master program. Then you could use the commands: 

LOAD PAYROLL/FT 1 
LOAD PAYROLL/PT2 

to get modules into memory, and then type: MENU to load and execute menu. 
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MASTER 

Set Master Read/Write Drive 



MASTER (DRIVE = 3) 

a is the drive specification. If omitted Drive 0 is set as the master drive. 


This command allows you to assign a specified drive as the Master Read or 
Write drive in the system. When searching for a file, trsdos will start with the 
master drive. 

If the file is not found on the specified drive, trsdos will continue searching on 
the next higher-numbered drive. 


Example 

After you enter the command: MASTER (DRIVE= 1) Drive 1 becomes the 
master drive. 


PATCH 

Change the Contents of a Disk File 


patch file (add = aaaa, find = M?,chg = cc) 
file is the file specification 

add = aaaa specifies the address at which the data is found, aaaa is a four¬ 
digit hexadecimal number. 

find = bb specifies the string you wish to find (or compare to), bb is a 
hexadecimal sequence. 


chg = cc specifies the new contents for the byte(s). cc is a hexadecimal 
sequence. 

Note: This utility is for machine language programs only. 
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This command lets you make minor corrections in any disk file, provided that: 

1. You know the existing contents and location of the data you want to change. 

2. You want to replace one string of code or data with another string of the 
same length. 

You can use patch to make minor changes to your own machine-language 
programs; you won’t have to change the source code, re-assemble it, and re¬ 
create the file. 

Another application for patch is to allow you to implement any modifications to 
trsdos that may be supplied by Radio Shack. That way, you do not have to 
wait for a later release of the operating system. 




Sample Use 

Suppose you want to change seven bytes in a machine-language program file. 
First determine where the seven-byte sequence resides in ram when the program 
is loaded. Then make sure your replacement string is the same length as that 
of the original string. For example, you might write down the information 
as follows: 

File to be changed: vread 
Start address: x’5280’ 

Sequence of code to be changed: X’CD2D25E5' 

Replacement code: x 00000009 ’ 

Then you could use the following command: 

PATCH VREAD (ADD=5280»FIND=0CD2D25E5>CHG=00000009) 

PAUSE 

Pause Execution for Operator Action 


pause message 

message is the message to be displayed during the pause execution. This 
is optional. If omitted, pause will be displayed by itself. 
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This command is intended for use inside a do file so trsdos can print a message 
or reminder. 

To continue after the pause, trsdos prompts you with the message: 

PRESS <ENTER> TO CONTINUE 

Example 

PAUSE INSERT DISKETTE #21 

trsdos displays pause, next the message and then prompts you to press (ENTER) 
to continue execution. 

PAUSE 

PRESS <ENTER> TO CONTINUE 

trsdos displays pause and then next prompts you to press (ENTER) to continue. 
See build and do for sample uses. 


PROT 

Use or Change a Diskette’s Master Password 


PROT :</(PW,LOCK) 

:<f is an optional drive specification. If omitted, Drive 0 is used. 

pw tells trsdos you want to change the master password. 

lock tells trsdos to assign the master password to all unprotected user 
files. If omitted, the unprotected files remain unprotected. 


prot lets you use the master password to protect all unprotected files at once, or 
to change the master password. 

The master password will be needed to backup the diskette, so be sure to 
remember it! 

Note: The master password on the trsdos factory-release diskette is password. 
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Examples 

PROT :0 (PW) 

Tells trsdos to change the master password on the Drive 0 diskette, trsdos will 
prompt you first for the old master password, then for the new master password. 

PROT :1 (LOCK) 

Tells trsdos to assign the master password to all unprotected user files, trsdos 
will first prompt you for the master password. 


PURGE 
Delete Files 


purge :d (file-type) 

:d is the drive which contains the disk to be purged. 
fife-type must be one of the following: 

sys All System and User files (no Invisible) 
inv All Invisible and User files (No System) 
all All files on disk (User, System, Invisible) 

If file-type is omitted, trsdos defaults to User files. 


This command allows quick deletion of files from a particular diskette. To use 
purge, you must know the diskette’s master password, (trsdos System 
diskettes are supplied with the password password.) 

When the command is entered, trsdos will ask for the diskette’s password. 
Type in up to eight characters. Press (ENTER) if you typed fewer than eight 
characters. The System will then display user filenames one at a time, 
prompting you to kill or leave each file. 

Example 

PURGE : 1 

trsdos will purge user files from Drive 1. This would include basic programs. 
PURGE : 1 (INU) 

trsdos will purge all invisible files in Drive 1. 
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Note: System diskettes contain some files which are not shown in any of the 
directory listings. You may delete these files with a special form of purge: 


purge * :d (file-type) 


The asterisk tells trsdos to ask you if you want to delete the System files. If 
you do delete them, the diskette becomes a data diskette and may only be used 
in Drive 1, 2 or 3. 

The other parts of this command are as explained previously. However, be sure 
to do the purge using Drive 1, 2 or 3, since the diskette will become “non¬ 
system” during the purge. 



RELO 

Change Where Program Loads into Memory 


relo file (add = aaaa) 

file is the file specification. 

add = aaaa specifies the new load address, aaaa is a four-digit hexadecimal 
number referring to an address in the user memory, aaaa must be in 
the user area of ram. 


This command allows you to change the address at which the program loads into 
memory. It does not change the program itself. 

Note: This command may be useful in conjunction with dump. 


Example 

RELO PROGRAM/CMD (ADD=G578) 

trsdos will load the program program/cmd at the new memory address 
of 6578. 
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RENAME 
Rename a File 


rename oldname newname 

oldname is the old file name. 
newname is the new file name. 

The file name may include a drive specification and or password. 

The new file name should not include a drive specification or password. 


This command lets you rename a file or program. Only the name/extension 
is changed; the data in the file and its physical location on the diskette 
are unaffected. 

rename cannot be used to change a file’s password protection. Use attrib 
to do that. 

rename also checks to see that the intended new name does not duplicate a 
filename currently on the same diskette. If it does, the command is cancelled 
and an error message is displayed. 

Examples 

RENAME MATHPAK MATHPAK/BAS 

Tells trsdos to add the extension to the filename. 

RENAME ABCDE/DAT ABCDEF/DAT 
Tells trsdos to change the filename only. 

RENAME PAYR0LL1/TXT.GSR PAYR0LL2/TXT 

Tells trsdos to change the filename; the password is retained automatically. 
RENAME FILE1:3 FILE2 

Tells trsdos to change the filename of the file on Drive 3. 
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ROUTE 

Routing I/O Devices 


ROUTE (SOURCE = d£,DESTIN = Ml) 

source = aa specifies the source i/o device. 

destin = bb specifies the destination i/o device. 

aa and bb may be any meaningful combination of the following two-letter 
abbreviations: 

do (Display) 
pr (Printer) 
kb (Keyboard) 
ri (RS-232 Input) 

ro (RS-232 Output) 

If the source and destination options are omitted, trsdos resets i/o Drivers 
to their original i/o routes. The source and destination devices must both be 
output or both be input. 


This command allows you to route I/O devices automatically. For example, 
trsdos can route information from the Printer (PR) to the Display (DO). 

Note: route cannot be used in conjunction with the dual command. 

Examples 

ROUTE (SOURCE=PR »DESTIN=D0) 

trsdos will route your Printer output to the Display. 

ROUTE 

i/o drivers are returned to their original state. 

For further details on routing i/o see “Routing Input/Output” in the 
Model III Manual. 
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SETCOM 

Set Up RS-232-C Communications 


SETCOM (OFF,WORD = 3,BAUD = b, STOP = C,PARITY = d,ITWde) 

OFF turns RS-232-C Off. 

word = a is the number of bit/byte desired, a must be either 5, 6,7, or 8, 
depending on your needs. If omitted, the word length is not changed. 

baud = b specifies the baud rate, bmust be a decimal number between 50 
and 9600. If omitted, the baud rate is not changed. 

stop = c specifies the number of stop bits, cmust be either 1 or 2. If 
omitted, stop bits are not changed. 

parity =</determines whether the parity is odd, even, or none, rfmust be 3 
(none), 1 (odd), or 2 (even). If omitted, parity is not changed. 

mode type either wait or nowait 

Options must be entered in the order shown. 

If all the options are omitted, trsdos displays the current r$-232-c settings. 



This command initializes rs-232-c communications via the serial channel. Before 
executing it, you should connect the communications device to the Model III. 

See the Model III Operation Manual for a description of rs-232-c signals used. 

See Using the rs-232-c Interface in the Model III Manual for further details. 

Examples 

SETCOM (W0RD = 7»BAUD=300 »STOP=l»PARITY=3 »WAIT) 

This would set the rs-232-c to seven bit words, 300 baud, one stop bit, no parity, 
and place it in the wait mode. 

SETCOM 

The command without specifications will display the current settings. 

The following program will allow you to use your Computer as a terminal. For 
further information, refer to the Operation section of your Model III Operation 
Manual. 

Note: This program executes at 300 Baud. 

r\ 


62 






TRSDOS 


DEFINT A-Z 'INTEGER VARIABLE FOR SPEED 

POKE 1S890» 0 'DON'T WAIT FOR SERIAL I/O 

POKE 1B888. (5*1B)+5 'TX/RCV AT BAUD RATE 300 
DEFUSRO = &HQ05A: REM SET UP CALL TO $RSINIT 
X = USR0(0) 

DEFUSRI = &H0050 
DEFUSR2 = &H0055 
Cl = 1B872 
CO = 1B880 


'CHARACTER INPUT BUFFER 
'CHARACTER OUTPUT BUFFER 


5 

10 
15 
20 
40 
B0 
S5 
70 
80 
80 

110 X = USR1(0) 

120 C$ = CHR$(PEEK(Cl)) 'LOOK AT INPUT BUFFER 
130 PRINT C* 'IF C = 0. NOTHING HAPPENS 

140 ' CHECK FOR KEYBOARD INPUT 
150 C$ = INKEY$ 

'NO KEY. SO GO CHECK SERIAL 
'SELF ECHO 

'PUT CHARACTER INTO OUTPUT BUFFER 
'CALL $RSTX 

'GO CHECK SERIAL INPUT 


CHECK FOR SERIAL INPUT 

'CALL $RSRCV 


THEN 110 


1B0 IF C$ = 

1B5 PRINT C$: 

170 POKE CO. ASC(C$) 
130 X = USR2(0) 

200 GOTO 110 


TAPE 

Tape/Disk Transfer 


tape (s = source, d = destination) 

source and destination are abbreviations for the storage devices to 
be used: 

t Tape 

o Disk 

R Random access memory 

Note: tape can only be used with machine-language programs, basic 
programs must be CLOADed and csAVEed. 


This command transfers z-80 machine-language programs from one storage 
device to another. The following transfers are possible: 

• Tape to disk 
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• Disk to tape 

• Tape to ram 

Examples 

TAPE (S=T iD = D) 

Starts a tape-to-disk transfer, trsdos will prompt you CASS?. Select the desired 
baud rate (H for high, L for low), trsdos will then prompt you to press (ENTER) 
when the recorder is ready to play to the Computer. When you press (ENTER) , the 
tape will begin loading. 

Note: If no asterisks flash, the recorder volume may need adjustment or the 
baud rate setting may be incorrect. 

trsdos will read the file name from the tape and use that name for the disk file. 
It will copy the program to the first write-enabled diskette, starting with the 
master drive (see master). 

TAPE <S=D (D=T) 

Starts a disk-to-tape transfer, trsdos will prompt you for the desired cassette 
baud rate, then for the diskette file specification. Then it will tell you to press 
(ENTER) when the cassette recorder is ready to record from the Computer. 

TAPE (S = T *D = R) 

Starts a tape-to-RAM transfer, trsdos will prompt you for the cassette baud rate, 
and will tell you to press (ENTER) when the recorder is ready to play to the 
Computer. After loading the program, trsdos will begin execution at the 
transfer address specified on the tape. 



TIME 

Reset or Get the Time 


time hh:mm:ss 

hh:mm:ss specifies the hour hh, minute mm, and second ss. 

Each must be a two-digit decimal number between the following ranges: 
hh 0-23 

mm 0-59 
ss 0-59 

If hh:mm:ss is given, trsdos resets the time. 

If hh:mm:ss is not given, trsdos displays the current time. 
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This command lets you reset or display the time. 

Time uses a 24-hour clock. For example, 1:00 P.M. is displayed as 13:00. 

You initially set the time when trsdos is started up. After that, trsdos updates 
the time automatically, using its built-in clock. 


When you request the time, trsdos displays it in this format: 14:15:31 for 
2:15:31 P.M. 


Examples 

TIME 

Displays the current time. 

TIME 13:20:00 

Resets the time to 1:20:00 P.M. 

Note: If the clock is allowed to run past 23:59:59, it will re-cycle to zero, the 
date will be incremented, and the clock will continue to run. 


WP 

Write-Protect Via Software 


wp (drive= d) 

(/specifies the disk drive to be protected. If omitted, all drives will be 
unprotected. 


Diskettes can be protected from being overwritten by this command. It is a 
software write-protect rather than a hardware write-protect (such as the write- 
protect tab on the diskette). 

Only one drive may be protected at a time. 

To unprotect a drive, making it accessible to writing, simply enter the command 
wp without options or with a different drive number specified. The wp command 
will not override a write-protect tab. 
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Examples 

UP (DRIVE=1) 

trsdos will write-protect the disk in Drive 1. 

WP 

trsdos will eliminate write-protection on all drives. 



r\ 
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TRSDOS Utility Commands 

BACKUP 

Create an Exact Copy of an Original Disk 


backup .source -.destination 

-.source specifies the drive containing the original diskette. If omitted, 
trsdos will prompt you for this information. 

-.destination specifies the drive containing the diskette to receive the copy. If 
omitted, trsdos will prompt tor it. 

-.source and -.destination may reference the same drive. 




backup copies the contents of the source disk to the destination disk. This gives 
you a “safe” copy of the disk. Always keep an extra copy of data or programs 
you have stored on your disks. 

Note: Both source and destination diskettes must be write-enabled. 

trsdos will prompt you at each step after you type: BACKUP 

If you omitted the source/destination-drive numbers, trsdos will begin with the 
prompts: SOURCE DR I ME NUMBER. 

Type in the number of the drive that contains the source diskette and press 

mm. 

DESTINATION DRIVE NUMBER? 

Type in the number of the drive that will contain the destination diskette and 
press CENTER) . 

SOURCE DISK MASTER PASSWORD? 

Type in the password assigned to your source diskette. 

DISK CONTAINS DAT A t USE DISK OR NOT? 

Type in Y (Yes) or N (No). 

DO YOU WISH TO RE-FORMAT THE DISK? 

Type in Y (Yes) or N (No). 
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If you specified the source/destination drives, trsdos will request the 
password, skipping the first two steps. 

trsdos will then take charge of formatting and verifying the destination disk as 
well as letting you know if there are any errors or flawed tracks. 



CONVERT 

Model I to Model III File Conversion Utility 


CONVERT 


Model I formatted diskettes cannot be used in the Model III Disk System. 

However, the convert utility can read a Model I diskette and copy its non¬ 
system files onto a Model III trsdos diskette. This diskette may then be used 

normally in the Model III Disk System. The original Model I diskette may still —^ 

be used in a Model I Disk System, since it is unchanged by convert. 

convert does not convert or change data; it converts the file storage format. 

For this reason, Model I Disk basic programs may require slight changes before 
they will run properly in the Model III Disk System. Model I machine-language 
programs may require major or minor changes before they will run in the Model 
III Disk System. You may make these changes on the Model I diskette before 
using convert, or on the Model III diskette containing the converted files. 

For hints on program conversion, see: 

• Technical Information in this manual 

• Technical Information in the Model III Manual 

• The manual, Instructions for Converting Specified Model I Programs for use 
on trs-80 Model III. 

Drive Usage 

In two-drive systems, the files must be copied onto a Model III system diskette 
in Drive 0; in three- or four-drive systems, the files may be copied onto a data 
diskette in Drive 1, 2 or 3. 

During the conversion process, the Model I diskette is referred to as the 
“source”; the Model III diskette, the “destination.” The source diskette cannot 
be in the same drive as that of the destination diskette. 
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Password Protection 

convert is designed to preserve the password security of each file that it 
transfers. To accomplish this and still allow the copying of protected files, 
convert follows different procedures depending on the access and update 
passwords on each file. 

In the simplest case, a file has blank access and update passwords. The copied 
file will be given blank passwords. (If you have a Model I Disk System with 
trsdos 2.3, you may use the prot command to remove all passwords from all 
files. This will simplify the convert process. Do this on the Model I system 
before you attempt to convert to Model III.) 

In another case, the access and passwords are different. If the access password 
is blank and the update is not, then trsdos will prompt you for the update 
password. If you know the update password, type it in. The file will be copied 
with access and update passwords set to the old update password. If you don’t 
know the update password, simply press (ENTER) . The file will be copied with the 
access password set to blanks and the update password set to an unloiown value. 

If the access and update passwords are not blank and they are not the same, 
trsdos will not copy the file, but will print the message, FILE SKIPPED, and 
continue with the next file in the source directory. 

Sample Use 

Get the Model I diskette ready. If you have a Model I Disk System with trsdos 
2.3, try to remove all passwords from all your files. This will prevent any 
problems with passwords. The password protection may be restored with the 
Model III attrib or prot commands after the conversion is complete. 

Using the Model III Disk System, you must always have a Model III trsdos 
diskette in Drive 0. trsdos ready should be displayed. Type: CONVERT (ENTER) . 

The program will ask, SOURCE DRIVE?. Type in the number of the drive 
containing the Model I diskette, and press (ENTER) . Then the program will ask, 
DESTINATION DRIVE?. Type in the drive number and press (ENTER) . In two- 
drive systems, you must use Drive 0 as the destination. 

During the conversion process, the name of each file will be displayed as it is 
copied. If password information is needed, trsdos will prompt you for it. If 
you know the update password, type it in and press (ENTER) . The file will be 
copied and given the same update password. If you do not know the update 
password, simply press (ENTER) , in which case the file will be copied and given 
an unknown update password. 

If a file name on the source diskette is already used on the destination diskette, 
trsdos will print this message: FILE EXISTS. USE IT?. If you type Y, 
trsdos will copy the file. The previous contents of the Model III file will be 
lost. If you type N, trsdos will skip the file, and get the next one from the 
Model I diskette. 
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FORMAT 

Prepare a Data Diskette 



FORMAT id 

:d specifies the disk drive which contains the diskette to be formatted. It \d 
is omitted, trsdos will prompt you for this information. 


This command lets you prepare data diskettes (either new or disks which contain 
undesired data or programs), leaving a maximum amount of space for your 
program and data files. 

Note: Data diskettes may only be used in Drives 1, 2, and 3 except during a 
BACKUP or FORMAT. 

format takes a blank (new or magnetically erased) diskette, records track/sector 
boundaries on it, then initializes it with and creates a directory. 

When format detects a non-blank diskette, it will display a warning message: 

DISK CONTAINS DATA» USE DISK OR NOT? 

Type Y (Yes) and press (ENTER) if you do want to reformat, N (No) and press 
(ENTER) if you want to save the disk information. 

format will lock out any defective tracks to prevent data from being lost in 
these areas. 

If you begin to get read errors during access, reformat the disk. 



Example 

FORMAT : 1 

After you are prompted for DISKETTE NAME? and MASTER PASSWORD?, 
trsdos will format Drive 1. 

rs 
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HERZ50 

Set Up for 50 Hz AC power (non-USA users) 


DO HERZ50 

starts the utility to change the system for 50 Hz operation, herzso is a do- 
file. 


This utility is provided for customers in areas where the ac power is 50 rather 
than 60 Hz. It should not be used by any other customers, herzso simply places 
a patch on the diskette that changes the clock speed for 50 Hz users. 

herzso is a DO-file that makes a change in the software of trsdos. Only the 
Drive 0 diskette is changed. Be sure it is write-enabled before you start the do- 
file. Once the herzso change is done, it will remain in effect for that diskette. 

To perform the change, type: 

DO HERZ50 

Once the change has been made, you will need to reset the system to put the 
change into effect. This loads the new software into ram. 

LPC 

Line Printer Control 


LPC 


The lpc utility program allows trsdos to ignore multiple carriage return 
commands. Without lpc, a top-of-form (lprintchr$(12» command will add an 
extra carriage retum/line feed each time it is executed. Also, lpc masks the high 
bit of each data byte, allowing you to send certain intercepted codes to the 
printer. For instance, the basic statement lprintchr$(I 40 ) will send code MO¬ 
HS = 12 (LPRiNT chr$(12» to the Printer. 
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The printers that require lpc are: 

Line Printer III (26-1156) 

Line Printer VI (26-1166) 

Daisy Wheel WP50 (26-1157) 

Qume Daisy Wheel (26-1157 A) 

Daisy Wheel II (26-1158) 

and all future printers. 

Printers that do not require lpc: 

26-1150, 1152, 1153, 1154, 1159, and the a version of lpiii (26-1156A). 

You must load the lpc program before you load an application program. The 
easiest way to do this is to copy lpc onto your data/program diskette and then 
use the auto command to load lpc automatically each time you use the system. 
For instance, type: 

COPY LPC: 1 :0 (INTER) 

Then, to make lpc an auto command on the diskette, type: 

AUTO LPC/CMD fENTIff) 

Whenever you use your program diskette, lpc will automatically load into 
memory and you can use the program as usual. 

lpc locates into the highest available memory. There is no need to set MEMORY 
SIZE to protect lpc. It “hides” itself. However, you still need to set memory if 
required by your application program, lpc will be killed if the clear command 
is used. 

Warning: Once the lpc utility program is loaded and installed, you should not 
reload it except after a reset. Reloading re-installs the program and uses up more 
space each time! lpc will not execute if the Printer has been routed elsewhere. 
Also, if lpc has been executed and then the Printer is routed elsewhere, the 
original printer driver will regain control after the routing. 


MEMTEST 
Test Memory 


MEMTEST 


This program tests your Model Ill’s memory (read only and random access). In 
trsdos ready, just type MEMTEST and press (ENTER) . 
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The program automatically tests all memory locations, no matter what memory 
size you have. First it checks read only memory (rom); if everything is okay, it 
automatically goes on and checks random access memory (ram). If all ram 
checks out okay, the program continues. 

If the program detects a rom or ram error, it will display a detailed message. 
Repeat the test to make sure it is a valid error condition. Write the message 
down and contact your nearest Radio Shack for assistance. 

Note: memtest changes the entire contents of ram. Before running it, be sure 
you have saved any valuable code you may have in ram. 


XFERSYS 

Transfer System Files 


XFERSYS 


xfersys lets you upgrade your version of Model III trsdos by copying all 
system files from a new release diskette (source) onto a previously released 
diskette (destination) (i.e., version 1.2 to version 1.3, etc.). 

System files which already exist on the destination diskette are replaced by those 
from the source diskette. Files which do not exist on the destination diskette are 
added. User files (program and data) are unaffected. 

Steps to upgrade a diskette 

Make backup copies of all diskettes to be upgraded. This is an important 
precautionary step. These backup copies should be kept until the upgrading 
process is complete and confirmed. 

Note: Both source and destination diskettes must be write-enabled. 

Insert the new release of trsdos into Drive 0 and press the reset button. Then 
type XFERSYS flfiTEff) . 

After the program heading appears, trsdos will prompt you with DISKETTE TO 
CONVERT READY IN DRIVE 1 (Y/Q)?. Type Y (yes) or 0 (quit) and press 
dSTH). 

The upgrading process will then take place. When the process is complete, 
trsdos will tell you so and take you back to trsdos ready. 

Note: If an error occurs, including your trying to upgrade a non-system diskette, 
the operation will be cancelled and take you back to trsdos ready. 
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Technical Information 


Contents of This Section: 

Disk Organization 
File Structure 

System Routines for Assembly i/o 
Data/Device Control Blocks 
Physical and Logical Records 
Fundamental trsdos i/o Calls 
Additional Routines and Storage Addresses 
trsdos Error Codes/Messages 


Disk Organization 


Each trsdos system diskette contains a trsdos system, a utility command 
library, and a file directory. 

Each diskette is single-sided and has 40 tracks of information. Each track 
contains 18 sectors of 256 bytes each. 

Normally, data read/write operations may be initiated only at sector boundaries, 
and must consist of exactly 256 bytes. However, trsdos allows the user to have 
maximum flexibility with minimal effort by automatically blocking and de¬ 
blocking all file accesses to user-specified logical record lengths, even if this 
requires “spanning” of two sectors. 

The system disk file structure allows maximum use of disk file space by 
automatically segmenting files across a diskette in several small pieces. These 
pieces are correlated into one logically contiguous file by the system without 
your needing to know the physical file location. This structure eliminates time- 
consuming disk-packing operations. 


File Structure 


A trsdos file is composed of one or more segments of storage space. Each 
segment consists of from one to 32 physically contiguous granules of storage. A 
granule is the minimum allocatable unit of storage, and consists of three sectors 
(768 bytes). 

Since a file is always lengthened by granules, a small amount of free storage is 
generally present at the end of every file. This free storage allows minor file 
additions to be made in space which is physically contiguous to the file. 

Every time a disk file is extended (either initialized or lengthened), extra 
granules may be allocated to that file, depending on the file’s accumulated 
length, diskette space, saturation, etc. These extra granules, along with all 
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granules after the one containing the file’s eof mark, are recovered and returned 
to the system when the file is closed. 


A TRSDOS file 


LRN1 

LRN2 

LRN3 

LRN N 

EOF 

EXTENT 1 

EXTENT 2 





GRANULE 1 

GRANULE 2 


GRANULE 32 


GRANULE: 


SECTOR X 


SECTOR X +1 


SECTOR X + 2 


SECTOR: 

LRN: 


BYTE 1 

BYTE 2 

BYTE 3 


BYTE 256 


File: 


Logical Record Number, used to specify an individual, user-defined 
logical record. Such a logical record is the smallest unit of 
information which can be addressed during disk input/output (a 
physical record is the unit which is actually read from or written to 
disk). 

A group of logical records; the largest unit of information which can 
be addressed by a trsdos command. 


Sector: A physical record, composed of 256 contiguous bytes. 
Granule: The minimum allocatable unit of storage for any file. 
Extent: One contiguous allocation of granules. 


System Routines for Assembly-Language I/O 

This information is provided for customers who wish to write their own 
assembly level i/o routines. An explanation of the calling sequence and 
parameters for each necessary i/o routine is given. A knowledge of z-80 machine 
code is assumed. 

The following notations are standard in this section: 

(HL) = xxxx Registers hl contain the address of (point to) xxxx in machine 
format. (If address of xxxx = 34B2H then the values in the 
registers are: h = 34; L = B2). Other register pairs will also be 
indicated this way. 

A—xx Register A contains the numeric value of xx in binary form. 

Register a is used to return the trsdos error code for i/o calls. 

A complete list of error codes and their meanings appears at 
the end of this chapter. Other registers will also be indicated 
this way. 
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z = ok Zero flag is set (OK) if successful return from the system 

routines. 

x’nnnn’ Hard ram address in hex notation (e.g., 402D is X’402D’). 

or nnnnw 

lrl Logical Record Length, 1-255 bytes only. You can define 

records any length you wish up to 255 bytes maximum. A 
length of zero is a special case for physical records only, and 
indicates the lrl = 256 bytes. 

buffer 256 user-designated bytes in ram for trsdos to read sectors 

from or write sectors into. If lrl = o, this area is the 
responsibility of the user to manage before and after i/o. trsdos 
manages this area if lrl is between 1 and 255 bytes. Do not 
alter this area when using logical record processing. 

urec (User Record) The address of the contiguous ram byte-string 

assigned by the user as his logical record area. Its length must 
be equal to lrl. It is a different area from buffer. 

lsb/msb Least-significant byte followed by most significant byte. This is 

the standard z-so format for addresses. 

Sname The “$” is prefixed to all system locations and call routines, so 

they will not be confused with trsdos commands or utilities. 
For example, sopen. 


DCB before $OPEN and after $CLOSE 


The dcb (device control block) is defined as 50 contiguous bytes of ram 
designated by the user. Before $open and after $close, it is a left-justified, 
compressed (no spaces) ascii string, as in a standard trsdos filespec. The string 
is terminated with a carriage return. 


8 


16 


24 


! I I 1 I I I I i I I 

fi lename/ext 
I _ l _ I _ I _ l _ I _ t _l_ I _ l _ I 


1 -[- 1 - 1 - 1 - 1 - 1 - 1 - 1 - 1 - 1 — 

p a s s w o r d d $ 


J I I L 


J L 


J L 


Notes: /ext, .password, and :d are optional. 

$ stands for a carriage return (X’OD’) 
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DCB while $OPEN 


Address 

Length 

Explanation 

DCB + 0 

3 

Reserved 

+ 3 

2 

Physical Buffer address (lsb/msb) 

+ 5 

1 

Offset to delimiter at end of current record 

+ 6 

1 

File drive number residence 

+ 7 

1 

Reserved 

+ 8 

1 

eof offset of last delimiter in last physical record 

+ 9 

1 

lrl (logical record length) 

+ 10 

2 

nrn (next record #—$open sets = x'oooo’— lsb/msb) 

+ 12 

2 

ern (ending record # — (last in file) lsb/msb) 

+ 14 

50 

Reserved 


NRN Next Record Number defines which record is to be read or written by the 
next system call for sread or $write. It is automatically incremented by one 
after each system call. In order to process random files, use the $posn call to 
direct trsdos to the record you wish to transfer next. 

ERN Ending Record Number is the last record number currently in the file. It 
is put into the directory at sclose time, so if it is expected to be correct, the user 
must close his files after adding records to a file. This value may also be used to 
position to end of file so that new records may be added to the end of the file. To 
position to the end of file use a call to $posn with a record number of ern + 1 . 
$posn is described later. 

Physical and Logical Records in TRSDOS 

A physical record is defined as one sector of disk. One sector of disk contains 
256 user data bytes. The artificial term “granule” is defined to be 3 sectors of 
disk space. There are 6 granules on each of the 40 tracks on the disk. A granule 
is the least amount of space allocated by trsdos. For programming purposes, 
the physical records in a file are numbered from 0 to N. The largest record 
number (N) in a file will then be 3 times the number of granules allocated minus 
one ((3*G) - 1). All trsdos granule allocations are made as needed at the time 
of write, not when the file is created. 


Bytes 

Sectors 

Granules 

Ttacks 

Disk 

256 

1 

— 

— 

— 

768 

3 

1 

— 

— 

4608 

18 

6 

1 

— 

184320 

720 

240 

40 

1 


Disk Space Table: For each 514" Disk Drive 



A logical record is defined by the user of trsdos. It may be anywhere from 1 to 
255 bytes in length. Once a file is opened with a specific lrl (Logical Record 
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Length), the length is fixed until the file is closed. To change a file’s lrl, you 
must close it and re-OPEN it with the new lrl. 

Each opening of the file sets a single, fixed record-length, trsdos will “block” 
logical records into (or from) one physical record for maximum space utilization 
on the disk. 

Blocking is putting more than one logical record into one physical record. For 
instance, four 64-byte logical records will fit into one 256-byte physical record. 
A logical record may be broken into two parts by trsdos in order to fill the last 
portion of one physical record entirely before beginning to use the next physical 
record (i.e. records are spanned). This occurs when the physical record length is 
not an even multiple of the logical record length. 

If the user wishes to do his own blocking, he may specify a logical record length 
of 0 bytes at the time of init/open and must himself manage the contents of the 
physical record buffer area of 256 bytes, trsdos will not move a logical record 
for the user if lrl = 0 ; in this particular case it will only read/write the physical 
record to/from the buffer. Once control is shifted to your program, you will have 
about 20 bytes of stack size left. 


Fundamental TRSDOS I/O Calls 

There are 17 fundamental trsdos routines involved in handling file i/o. These 
are: 


$BACKSPACE 

$POSN 

SCLOSE 

SPUTEXT 

$DIVIDE 

SRAMDIR 

$DMULT 

$READ 

$FILPTR 

SREWIND 

$INIT 

SSYNTAX 

SKILL 

$VERF 

$OPEN 

SWRITE 

SPOSEOF 



The detailed calling sequences and discussions for each of these routines follow. 
Note that all of these system calls use register f and do not restore its value 
before return. In order to apply this data properly, you should read through all of 
these descriptions and clear up all of the points that are not obvious to you by 
using other reference materials. If you are successful in doing this you will find 
that trsdos is a workable tool for your programming ideas. 

$INIT—17440/X’4420’ 

Unit is provided as an entry point to trsdos which will create a new file entry 
in the directory and open the dcb for this file, sinit scans the directory for the 
filespec name given in the dcb. If the filespec name is found, sinit simply opens 
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the file for use. If the name is not found, a new file is created with the filespec 
name. 


Entry Conditions 

(HL) = buffer (see beginning of this section for notation) 
(DE) = DCB 
B = LRL 
CALL $INIT 


Exit Conditions 

iy = changed 
z = OK 

c carry flag is on if a new file was created 
a = trsdos error code. (Error codes listed at end of this chapter) 

$OPEN—17444/X’4424’ 

$open provides a way to open the dcb of a file which already exists in the 
directory. The dcb must contain the filespec of the file to be opened before entry 
to SOPEN. 

Entry Conditions 

(HL) = BUFFER 
(DE) = DCB 
B = LRL 
CALL $OPEN 

Exit Conditions 

Z = OK 

z = 0 if file does not exist. 
a = trsdos error code. 
iy = changed 


$POSN—17474/X’4442’ 

$posn positions a file to read or write a randomly selected logical record. Since 
it deals with logical records, the proper computation is done to locate which 
physical record(s) contain the data. Following a $posn with a $read or swrite 
will transfer the record to/from ram. 
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Note that positioning to logical record zero sets the file to read the first logical 
record in the file. To position to end of file in order to add new records onto the 
end, use the record number ern+ i. 

Entry Conditions 

(DE) = dcb (must have been opened previously) 
bc = Logical record number to position for. 

CALL $POSN 

Exit Conditions 

Z - OK 

a = trsdos error code. 

$READ— 17462/X’4436’ 

If lrlo, $read transfers the logical record whose number is in the dcb as nrn 
into the ram area addressed as urec for the length lrl as defined at open time. 
The record comes from “buffer” defined at open time. If trsdos must read a 
new physical record to satisfy the request, it will do so. “Spanned” logical 
records will be re-assembled as necessary, sread automatically increments nrn 
by 1 in the dcb after the transfer is completed. $init/open set nrn = X’oooo’ in 
order to read the first record with the first read. 

If lrl — o, $read transfers one physical record into buffer, defined at open 
time, from the disk file. Registers hl are ignored. $read increments nrn as 
above. 

Entry Conditions 

(HL) = urec if lrl is not zero. Unused if lrl = o. 

(DE) = DCB 
CALL $READ 

Exit Conditions 

Z = OK 

a = trsdos error code. (eof = x’ic’ or X’lD’) 

(see errors 28,29 for eof or nrf) 

$WRITE— 17465/X’4439’ 

If lrlo, swrite transfers the one logical record from the ram area addressed 
as urec for the length lrl as defined at open time. The record goes into the 
buffer which was defined at open time. If trsdos must write a physical record 
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in order to satisfy the request, it will do so. “Spanning” will be handled by 
trsdos as necessary. At $init $open time die dcb value of nrn is set to x'oooo’ 
so that the first record will be written. After each logical record is transferred, 
the nrn value in the dcb will be incremented by 1 . 

If lrl= o, swrite transfers one physical record from buffer into the disk file 
using the nrn in the dcb. buffer is defined at $init/open time only. The dcb 
value nrn is updated as above, after die write. 


Entry Conditions 

(HL) = urec if lrl is not zero. Unused if lrl = o 

DE = DCB 
CALL $ WRITE 


Exit Conditions 

Z = OK 

a = trsdos error code. 


$VERF—17468/X’443C’ 

The only difference between $verf and swrite is that sverf writes one physical 
record to disk and then reads it back into a special trsdos ram area not defined 
by the user. This special area and the original write buffer are then compared 
byte by byte to assure that the record was successfully written. 


Entry Conditions 

(HL) = Same as swrite above. 
(DE) = DCB 
CALL SVERF 

Exit Conditions 

Z = OK 

a = trsdos error code. 


SPUTEXT—17483/X ’444B ’ 

This routine will add an extension to a filename if an extension does not already 
exist. An extension to a filename may be useful for identifying the type of data 
in the file. 
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Entry Conditions 

(DE) = DCB 

(HL) = The extension to be added to the file 

CALL SPUTEXT 

Exit Conditions 

None 


$BKSPC—17477/X’4445’ 

This routine positions the file record pointer to the previous record. 

Entry Conditions 

(DE) = DCB 
CALL $BKSPC 

Exit Conditions 

z = Valid position 

nz = Invalid position in file 

SREWIND— 17471/X’443F’ 

Point to the beginning of the file. This routine positions the file pointer to the 
first record in the file. This is useful when the same file must be processed more 
than once. 

Entry Conditions 

(DE) = DCB 

Exit Conditions 

z = Good file specification 
nz = Bad file specification 

CALL SREWIND 



SPOSEOF— 17480/X’4448’ 

Point to the end of file. This routine positions the file pointer to the last record in 
the file. This may be used to extend a sequential access file. 

o 
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Entry Conditions 

(DE) = DCB 
CALL SPOSEOF 

Exit Conditions 

z = Good file specification 
nz = Bad file specification 


$SYNTAX—17436/X’441C’ 

Move a file specification to dcb. This routine takes a file specification and 
checks it for validity and moves it to a dcb so that the file may be opened. 


Entry Conditions 

(HL) = Filename 
(DE) = DCB 
CALL SSYNTAX 

Exit Conditions 

z = Good file specification 
nz = Bad file specification 


SDIVIDE— 17489/X’4451’ 

The divide routine takes a 16-bit dividend and an eight-bit divisor. After 
division, the quotient replaces the 16-bit dividend and the remainder replaces the 
eight-bit divisor. 


Entry Conditions 

hl = Dividend 
a = Divisor 

CALL SDIVIDE 


Exit Conditions 

hl = Quotient 

a = Remainder (0 indicates no remainder). 
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$DMULT—17486/X’444E’ 

The multiply routine uses a 16-bit multiplicand and an eight-bit multiplier. After 
multiplication takes place, the product replaces the 16-bit multiplicand. 

Entry Conditions 

hl = Multiplicand 
a = Multiplier 

CALL SDMULT 


Exit Conditions 


h = High order byte 
L = Middle order byte 
a = Low order byte 


H 


High 


Middle 


Low 


$RAMDIR—17040/X’4290’ 

This routine allows you to examine a diskette directory (one entry or the entire 
directory) or the diskette’s free space. The information is written into a user 
specified ram buffer. 

Only non-system files will be included in the ram directory. 


Entry Conditions 

hl = ram Buffer. If c = 0, size = 1761 [max #*22+ 1]. If c = l to 96, 
size =22. Ifc = 255, size = 64. 
b = Specified drive number 
c = Function switch: 


Contents of C 
0 

1-96 

255 


Results 

Gets entire directory into ram. (See ram Directory Format). 

Gets one specified directory record into ram, if it exists. (See 
ram Directory Format). 

Gets free-space information (See ram Directory Format). 


CALL SRAMDIR 


Exit Conditions 

nz = Error occurred. 

z = No error. (HL) = directory or free-space information. 



.o 
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RAM Directory Format 

The directory is made up of records, one per file. All values are hexadecimal. 
Each record placed in user ram is in the following format: 

Byte Number Contents 

0-14 filename/ext:d (left-justified followed by spaces) 

15 Protection Level, binary 0-6 

16 Byte eof, binary 0-255 

17 Logical record length, binary 0-255 

18-19 Last sector number in file, binary lsb, msb 

20-21 Number of Granules allocated (LSB,msb> binary 

22 “ + ” (marks the end of directory list after entire directory.) 

Free Space Message Format 

***nnnnn Free Granules*** 

Where nnnnn is a decimal number. The entire message is Ascii-coded. 

$FBLPTR—17037/X’428D’ 

This routine provides information on any user file that is currently open. It 
enables you to obtain the drive number and the logical file number for any file 
and should be used in conjunction with sramdir. 

Entry Condition 

(DE) = Data Control Block (dcb) defined when file was opened. 

CALL SFILPTR 

Exit Conditions 

nz = Error occurred. 

z = No error. The following registers are set up: 
b = Which drive contains the file (0,1,2, or 3). 
c = Logical file number (1-96) 

Note: This operates with user files only. 

$CLOSE—17448/X’4428’ 

$close closes a file from the last processing done. It is very important to do 
a sclose on every file opened before the program ends. If you do not close 
a file, the directory entry for this file is incorrect if any new records have been 
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written into the file. Other cases are not given here, but it is very important to 
trsdos that all of the “housekeeping” be complete for file management. 

Entry Conditions 

(DE) = DCB 
CALL $CLOSE 

Exit Conditions 

Z = OK 

A = trsdos error code. 


$KILL—17452/X’442C’ 


Skill deletes the directory entry for a file and releases the disk storage. The file 
may be open or closed; skill will operate in either case. 

Entry Conditions 



(DE) = DCB 
CALL SKILL 


Exit Conditions 


Z = OK 

a = trsdos error code. 


Additional Routines and Storage Addresses 
$JP2DOS—16429/X’402D’ 


This routine transfers control to trsdos ready. 


Entry Conditions 


JP SJP2DOS 


Exit Conditions 



None 








$DATE— 12339/X’3033’ 

$TIME—12342/X’3036’ 

These routines return the date and time in ascii format: 

Date: mm/dd/yy 
Time: hh/mm/ss 

Entry Conditions 

(HL) = Eight-byte buffer to receive the date/time text 

CALL $DATE 
CALL $TIME 

Exit Conditions 

(HL) = Date or time text 

SDATLOC—16922/X’421 A’ 

$TIMLOC—16919/X’4217’ 

These locations store the date and time in binary format: 

Sdatloc (Three bytes): yy dd yy 
$timloc (Three bytes): ss mm hh 

$ERRDSP— 17417/X’4409’ 

This routine displays a trsdos error message determined by the contents of the 
accumulator (A). This register contains an error code (0 = no error) after 
completion of any system routine. 

Entry Conditions 

a = trsdos error code (see Table at the end of this section). In a trsdos error 
code, bits 6 and 7 are normally reset (off). So serrdsp interprets them as 


controls. 


Not Set (Normal 

Bit# 

Set 

Condition) 

7 

Return to caller upon 

Return to trsdos upon 


completion 

completion 

6 

call serrdsp 

Give detailed error message 

Give error number only 


W 
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Exit Conditions 

None 


Sample Use 

CALL $SYSRTN 5 ANY SYSTEM ROUTINE 

JR Z.OKGO i CHECK FOR ERROR 

5 THE FOLLOWING INSTRUCTION SETS BIT G (DETAILED 
; ERROR MESSAGE) AND BIT 7 (RETURN TO CALLER AFTER 
i DISPLAYING MESSAGE 

OR C0H i BINARY 11000000 

CALL $ERRDSP i NOW CALL ERROR DISPLAY 

i CONTINUE HERE UPON RETURN FROM ERROR DISPLAY 
i YOUR ERROR HANDLER MAY GO HERE 


OKGO .CONTINUATION AFTER $SYSRTN WITH NO ERROR 


$DSPDIR—17433/X’4419’ 

This command displays the directory listing of all non-protected user files in a 
specified drive. 


Entry Conditions 

(X’4271’) = ASCII-coded drive number “0,” “1,” “2,” or “3” 
CALL SDSPDIR 


Exit Conditions 

All registers are changed. 

SCOMDOS—17049/X’4299’ 

This routine executes a trsdos command and returns to trsdos ready. 


Entry Conditions 

(HL) = Text of trsdos command, terminated by x’od.’ 
jp SCOMDOS 

Exit Conditions 

None 
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$CMDDOS—17052/X’429C ’ 

This routine executes a trsdos command and returns to the caller. 

Entry Conditions 

(hl) = Text of trsdos command, terminated by X’OD.’ 

Exit Conditions 

All registers are changed. 

Caution: trsdos commands will overlay ram up to x’6fff: 

$CMDTXT— 16933/X’4225’ 

This is the start address of a buffer containing the last command line entered 
under trsdos ready. Using this buffer, your program may recover parameters 
that were included in the last command line. 

For example, given a program named editor/cmd, we want the operator to 
select an input file name when the program is loaded and executed from trsdos 
ready: 

TRSDOS READY 
EDITOR myfile 

The program, editor, can recover the name of the file in the scmdtxt buffer. 

Note: On entry to a program, (hl> = First non-blank character following the 
program name. 

$MEMEND— 17425/X’4411’ 

This storage location contains the highest address available. It is normally the 
same as the physical end of ram, but you may change it for special purposes. 

The address is in lsb, msb sequence. 
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TRSDOS Error Codes/Messages 

0 No Error Found 

1 CRC Error During Disk I/O 

2 Disk Drive Not In System 

3 Lost Data During Disk I/O 

4 CRC Error During Disk I/O 

5 Disk Sector Not Found 

6 Disk Drive Hardware Fault 

7 "Undefined Error Code** 

8 Disk Drive Not Ready 

9 Illegal I/O Attempt 

10 Required Command Parameter Not Found 

11 Illegal Command Parameter 

12 Time Out On Disk Drive 

13 I/O Attempt To Non-System Disk 

14 Write Fault On Disk I/O 

15 Write Protected Disk 

16 Illegal Logical File Number 

17 Directory Read Error 

18 Directory Write Error 

19 Invalid File Name 

20 GAT Read Error 

21 GAT Write Error 

22 HIT Read Error 

23 HIT Write Error 

24 File Not Found 

25 File Access Denied Due to Password Protection 

26 Directory Space Full 

27 Disk Space Full 

28 Attempt to Read Past EOF 

29 Attempt to Read Outside of File Limits 

30 No More Extents Available 

31 Program Not Found 

32 Invalid Drive Number 

33 "Undefined Error Code** 

34 Attempt to Use Non-program File as a Program 

35 Memory Fault During Program Load 

36 "Undefined Error Code** 

37 File Access Denied Due to Password Protection 

38 I/O Attempt to Unopen File 

39 Invalid Command Parameter 

40 File Already In Directory 

41 Attempt to Open File Already Open 
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Start-Up 

Under trsdos ready, type: 

BASIC CENTEff) 

trsdos will load basic and begin the “initialization dialog.” 

If you want to recover a Disk basic program after returning to trsdos for a dir 
or other trsdos command, use this command under trsdos ready: 

basic * Center) 

You will go directly to Basic’s ready mode without any initialization dialog. If 
you had a program in memory, it should still be there. You may not be able to 
run the program. To be safe, you should immediately save the program, go to 
trsdos, then start basic again (no asterisk). 

Note: If you have overlaid user memory while in trsdos, your program will be 
erased. In such a case, you should not restart basic, but should use the normal 
basic start-up procedure. 


Initialization 

When you start Disk basic, you are first asked, HOW MANY FILES?. This lets 
you specify the maximum number of files that will be “open” or in use at once. 
(See open.) Type in an appropriate number and press (ENTER) , or simply press 
(ENTER) and basic will provide for three files. 

For example, if your program requires one input file and one output file, you 
should ask for two files. 

Note: Normally, basic will give all your data files a record length of 256. 

(See File Access Techniques.) If you wish to set the record length of each file 
individually, use the suffix v for “Variable” after the number of files. 

For example, 

HOW MANY FILES? 30 CENTER) 

tells basic to give you three file-buffers, and to let you set the record length of 
each file when that file is first opened. 

Note: Disk basic automatically creates a buffer for loading, saving, and 
merging basic programs. This buffer exists in ram below any data file buffers 
you may request. It is always available for program i/o, regardless of how you 
answer the files? question. 
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After you answer the files question, basic will ask: MEMORY SIZE? Simply 
press (ENTER) without typing a number. You will then have the maximum amount 
of ram available for use by basic. 

If you will want to load and use machine-language programs or routines, you 
will have to protect your basic memory from these machine-language programs. 

In such a case, respond with the highest memory address (in decimal form) you 
want basic to use for storing and executing your basic programs. Addresses 
above the number you specify will then be protected from use by basic. 

Example: 

MEMORY SIZE? 32000 (ENTER) 

causes basic to protect addresses above 32000. If you have 16K of ram, this 
means that you’ll have 32767-32000 = 767 bytes protected for storing your 
machine-language routines. 

After you answer the MEMORY SIZE? question, Disk basic will display the 
follojwing information: 

1. Which version of Disk basic you are using 

2. Copyright information 

3. The number of free bytes available 

4. The number of concurrent files you have requested. 

To exit from Disk basic and return to the trsdos ready mode, type: 

CMD"S" (ENTER) 

This results in a normal return to trsdos, without re-initialization of the system. 
You may recover your program if you haven’t changed user memory while in 
trsdos. Use basic *. 
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Enhancements to Model 



BASIC 


Disk basic adds many features which are not disk-related. They are listed below 
along with abbreviated descriptions. Detailed descriptions follow in alphabetical 
order. 


&H 

&o 

Abbreviations 

CMD“A” 

CMD“B” 

CMD “C” 

CMD“D” 

CMD“E” 

CMD“I” 

CMD“J” 

CMD“L” 

CMD“ 0 ” 

CMD“P” 

CMD“R” 

CMD“S” 

CMD“T” 

CMD“X” 


CMD“Z” 
DEFFN 
DEF USR 

INSTR 
LINE INPUT 
MID$ = 

name 

USRrt 


Hexadecimal-constant prefix 
Octal-constant prefix 
Many commands have abbreviations 
Return to trsdos with error message 
Enable/Disable (BREAK) 

Delete spaces and remarks from a program (compression) 

Display directory for specified drive 

Display previous trsdos error 

Return a command to trsdos 

Convert calendar date 

Load Z-80 subroutine or program file into ram 

Alphabetizes (sorts) a string array only 

Check printer status 

Start real-time clock display 

Normal return to trsdos (jump to exit routine) 

Turn off real-time clock display 

Cross-reference of reserved words, string variables, or 

strings in a program 

Duplicate output to Display and Printer 

Define BASic-statement function 

Define the entry point for an external machine-language 

routine 

Instring function; find the substring in the target string 
Input a line from keyboard 

Replace portion of the target string (used on left of equals 
sign) 

Renumber a program in ram 

Call external routine (n = 0,1,2,. . . ,9) 


&H and &O (hex and octal constants) 

Often it is convenient to use hexadecimal (base 16) or octal (base 8) constants 
rather than their decimal counterparts. For example, memory addresses and byte 
values are easier to manipulate in hex form. &h and &o let you introduce such 
constants into your program. 

&h and &o are used as prefixes for the numerals that immediately follow them: 
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&h dddd 

dddd is a 1 to 4 digit sequence composed of hexadecimal numerals 

0,1,...9,A,B,...,F. 

&o ddddd 

ddddd is a sequence of octal numerals 0,1 ,...,7 and &o ddddd< = 177777 
decimal. 

Note: The o can be omitted from the prefix &o. Therefore &o ddddd=&ddddd. 


0 * 


The constants always represent signed integers. Therefore any hex number 
greater than &H7FFF, or any octal number greater than &. 011111 , will be 
interpreted as a negative quantity. The following table illustrates this: 


Octal 

Hex 

Decimal 

&1 

&H1 

1 

&2 

&H2 

2 

&77777 

&H7FFF 

32767 

&100000 

&H8000 

-32768 

&100001 

&H8001 

-32767 

&100002 

&H8002 

-32766 

&177776 

&HFFFE 

-2 

&177777 

&HFFFF 

-1 


Hex and octal constants cannot be typed in as responses to an input prompt 
or be contained in a data statement. Often the hex or octal constant must be 
enclosed in parentheses to prevent a syntax error from occurring. 


Examples 

PRINT 8.H5200 » 8.051000 


prints the decimal equivalent of the two constants (both equal 20992). 


POKE 8.H3C00 1 42 


puts decimal 42 

3C00. 


(ascii code for an asterisk) into video memory address hex 
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Model III Disk BASIC Abbreviations 




Abbreviation 

Meaning 


List Previous Program Line 

® 

List Next Program Line 

CD 

List Current Program Line 

CD 

Edit Current Program Line 

(SHIFT) ® 

List First Program Line 

(SHIFT) ® (ZJ 

List Last Program Line 

lxx 

List Program Line xx 

EXX 

Edit Program Line xx 

DXX 

Delete Program Line xx 

AXXX,XXXX 

Automatic Line Numbering Beginning at Line xxx, 
Incrementing by xxxx. 

CMD “A” 


Return to TRSDOS 

CMO“A” 


This command allows you to return to trsdos with an error message: 
OPERATION ABORTED 

Sample Use 

After an input/output error occurs in a basic program, you might want to exit to 
trsdos and print a message. 

CMD"A" 

the following will be displayed: 

OPERATION ABORTED 
TRSDOS READY 


****************** 


» 
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CMD “B” 

Enable/Disable BREAK Key 


CMD “B”, " switch” 

switch is either on or off. switch must be enclosed in quotation marks. 


This command enables or disables the (BREAK) key. While the function is “off,” 
the (BREAK) key will be ignored except during cassette or printer output or during 
serial input/output. 

The (BREAK) key will remain disabled even after the program has ended. To 
enable the (BREAK) key, use the cmd“B”,“on” command. Returning to trsdos 
via the cmd“S” or cmd“I” commands will also enable the (BREAK) key. 

Examples 

CMD"B" ."OFF" 

Disables the (BREAK) key. 

CMD"B"»"0N" 

Returns the (BREAK) key to its normal function. 

CMD “C” 

Compress Program 


cmd “C”, options 

options may be either r (delete remarks) or s (delete spaces). If both 
options are omitted, remarks and spaces are deleted. If only one is 
omitted, only the specified action is taken. 


This command allows you to compress a program so that it requires less 
ram and less storage space on diskette. You can elect to remove all remark 
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statements (beginning with rem or ’) or to delete all spaces between basic 
keywords. Spaces inside quotes will not be deleted. 

Example 

Your program reads as follows: 

850 RESTORE: ON ERROR GOTO 800 
860 READ COMPANY* 

870 PRINT RIGHT*(COMPANY**2)»: 

880 END 

If you want to delete the Remarks (lines 850 and 860), type in the command: 
CMD"C"tR 

and the program will now read: 

850 RESTORE: ON ERROR GOTO 800 
860 READ COMPANY* 

870 PRINT RIGHT*(COMPANY* , 2 ) »:G0T0 860 
880 END 

If you then wanted to delete the spaces, type in: 

CMD"C"»S 

and the program would read: 

850 RESTORE:ONERRORGOTO800 
860 READCOMPANY* 

870 PRINTRIGHT*(COMPANY* >2)*:GOTO860 
880 END 

You could obtain the same results by typing: 

CMD H C" 

Note: Always provide the closing quotes on string literals in your basic 
program. Otherwise cmd“C” may not function properly. For example, in 

10 PRINT "THIS IS A TEST" 

the second quote should be used even though omitting it will not cause an error. 

CMD“D” 

Display the Directory of a Specified Drive 


'DOG PROGRAM 
'PET STORE 
GOTO 860 


CMD“D:<f’ 

rfis the drive specification 







By entering the command cmd“d:J”, you can obtain a specified diskette’s 
directory from basic without returning to trsdos. Only unprotected, visible 
files will be displayed. The drive specification is not optional and must be 
specified for all drives, including Drive 0. 

Example 

If you type in the command: 

CMD"D:1" 

the directory for Drive 1 will be displayed. 

CMD“E” 

Display Previous TRSDOS error 


CMD“E” 


This command displays the last trsdos error message. If no errors have 
occurred prior to the command, the message NO ERROR FOUND will be 
displayed. 

Example 

If you have a two-drive system (0 and 1) and you type: 

SAVE "PR0GRAM:3" 

Disk basic will return a DISK I/O ERROR. To find out what kind of i/o error 
occurred, type: CMD"E" (ENTER) and Disk basic will return with DISK DRIVE 
NOT IN SYSTEM. 



CMD“I” 

Execute TRSDOS Commands from Disk BASIC 


cmd'T’, command 

command s a string expression containing a trsdos command or a z-eo 
program file name. If it is a string constant, it must be enclosed in 
quotes. 
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You may execute trsdos commands directly from basic by using cmd“I”. 

This is similar to cmd“S”, except that it lets you include a command or z-so 
program for trsdos to execute. 

As long as basic is not overwritten by the execution of the program or 
command, control will return to basic; otherwise, control will return to trsdos. 
(trsdos commands all overlay basic; your z-so program may not if it loads 
above basic.) 

Example 

CMD" 1 11 ("PROGRAM" 

returns you to trsdos and executes the program file program. 

CMD"I"(A$ 

returns you to trsdos and executes the command contained in A$. 

CMD“J” 

Calendar Date Conversion 




cmd j", source, destination 

source is a string expression containing the date to be converted. Its 
contents may be in either of two formats; 

A) mm/dd/yy 

B) -yy/ddd 

Format a gives the date in month-day-year sequence. Format b gives 
the day of the year (from 1 to 365 or 366 for leap years). In format b, 
the hyphen is required. 

destination is a string variable to contain the converted date. If source is in 
format a, destination will contain the day of year. If source is in 
format b, destination will contain the date in format a. 


O' 


This command converts dates back and forth between two formats: the standard 
month, day, year, sequence; and a year, day of year, sequence. The content of 
the source string determines which way the conversion goes. 
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Example 

CMD"J"» "11/30/80"» D$ 

Returns the day of the year in d$. 

CMD"J "t "-79/300"» D* 

Returns the month, day, year, equivalent in D$ (the date for the 300th day 
of 1979). 

Sample Program 

10 CLEAR 50 

20 LINE INPUT"ENTER FIRST DATE (MM/DD/YY) "5 FD$ 

30 LINE INPUT"ENTER SECOND DATE (MM/DD/YY) "!SD$ 

40 CMD"J"* FD$» Dl* 

50 CMD"J"* SD$ # D2$ 

60 Y1 = VAL(RIGHT$(FD$ »2)) 

70 Y2 = VAL(RIGHT*(SD$ »2)) 

80 J1 = OAL(RIGHT*(D1$ »3)) 

90 J2 = VAL(RIGHT$(D2$ ,3)) 

100 SI = Y1*365 + J1 
110 S2 = Y2#365 + J2 

120 PRINT "THE INTERVAL BETWEEN DATES IS" 5 
130 PRINT ABS(S1-S2); "DAYS "5 
140 PRINT "(IGNORING LEAP-YEARS)." 

150 INPUT "<ENTER> TO CONTINUE"! A$ 

160 GOTO 20 

CMD“L” 

Load Z-80 Routine into RAM 


cm-i",routine 

routine is a string expression containing a file specification for a z-so 
routine or program created by the dump command. If routine is a 
string constant, it must be enclosed in quotes. 


CMD“L” loads a z-80 (machine-language) routine into ram. It would normally 
be used to load a z-so subroutine which is to be accessed directly from basic. 
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The z -80 routine should load into high-RAM and must not overlay the memory 
protect area reserved when you first entered basic (i.e., the MEMORY SIZE? 
prompt). If you do not overlay basic or trsdos, control will return to basic 
after the program is loaded. 

Example 

The command: 

CMD"L" ."PROG" 

will load a program file named prog into ram. 

CMD"L">Pt 

will load a program which has been specified as p$. 

CMD“0” 

Sort (“Order”) an Array 



cmd “0”,jt ,array (start) 

jr is an integer variable containing the number of items to be sorted. 

array (start) specifies an array element. The array contains the data to be 
sorted, and start is the subscript of the first element to be sorted. The 
array must be one-dimensional, string type. The string elements in 
array may be of any length. 


This command sorts (orders) a one-dimensional string array, i.e., a list. You 
may sort all or part of the array, depending on the values you give to x and start. 


Sample Program 

10 CLEAR 10 * 25 + 50 'ROOM FOR 10 WORDS + EXTRA 
20 DIM At(9) 'LIST OF TEN (0-9) 

30 FOR WD = 0 TO 9 

40 PRINT "ENTER WORD #"5 WD+1 

50 INPUT At(WD) 

E0 NEXT WD 

70 NX=10: CMD"0" . NX. At(0) 

90 PRINT "HERE IS THE SORTED LIST" 

90 FOR WD=0 TO 9 
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100 PRINT A$(WD> 

110 NEXT WD 

CMD“P” 

Check Printer Status 


cmo “P ", status 

status is a string variable 


cmd“P” makes it possible for Disk basic to check the status of the printer. 

Unlike the video display, the printer is not always available. It may be 
disconnected, offline, out of paper, etc. In such cases, when you try to output 
information to the printer, the Computer will wait until the printer becomes 
available. It will appear to “hang up.” To regain keyboard control (and cancel 
the printer operation), press (BREAK) . 

Suppose you have a program which uses printer output. If a printer is not 
available, you don’t want the Computer to stop and wait for it to become 
available. Instead, you may want to print a message such as PRINTER 
UNAVAILABLE and go on to some other operation. 

To accomplish this, you need to check the printer status. cmd“P” can be used to 
check the printer’s status at any time. It returns the contents as an Ascii-coded 
decimal number. The specific value of this number depends upon the type of 
printer you are using as well as its status at any particular time. The value may 
then be printed or examined by the program. 

Only the four most significant bits are used in this “status byte.” In binary, 
these must be: “0011” or else the print operation will not be attempted. To 
check for this “go” condition, and the status byte with 240 and compare the 
result with 48. The meaning of each status bit depends on which printer you 
use. See the printer owner’s manual for bit designations. 

Sample Program 

10 CMD"P"»X$ 

20 STZ = VAL(X$) AND 240 

30 IF STZ <> 48 THEN PRINT "PRINTER UNAVAILABLE": STOP 
40 PRINT "PRINTER AVAILABLE" 

50 REM PROGRAM MAY NOW CONTINUE 
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CMD“R” 

T\irn On Clock-Display 


CNID“R” 


This command controls the real-time clock display in the upper-right comer of 
the Video Display. When it is on, the 24-hour time will be displayed and 
updated once each second, regardless of what program is executing. 

Note: The real-time clock is always running (except during cassette or disk i/o), 
regardless of whether the display is on or off. 

Example 

To turn on the clock display type: CMD" R" To turn the display off, type: CMD"T" 

CMD“S” 

Return to TRSDOS 


CMD“S” 


To exit from Disk basic, returning control to trsdos, simply type in the 
command: 

CMD"S" 

To return to basic and recover your program, use BASIC *. However, recovery 
will not always be possible. See basic *. 

Example 

The basic prompt lets you know you are in Disk basic. 

READY 

> 
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To exit, type in: 

CMD"S" 

and the trsdos prompt will appear. 
TRSDOS READY 


***************** 


CMD“T” 

T\irn Off Clock-Display 


CMD“T” 


This command turns off the real-time clock display function. 
However, the clock continues to run. 


Example 

To stop the clock display update type: CMD"T” 
To start the display, type: CMD"R" 


CMD “X” 

Cross-reference of Program Lines 


cmd "X", target 

target is either a sasic reserved word (such as print) or a string-literal. If it 
is a reserved word, it must not be enclosed in quotes; if it is a string- 
literal, it must be enclosed in quotes. 
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W 

This command finds all occurrences of a reserved word or other string literal in 
the resident program. The “finds” are listed on the display as five-digit line 
numbers. 

To search for any basic reserved word (including reserved arithmetic operators), 
use the keyword as-is. To search for anything else (including variable-names and 
text), enclose the text inside quotes. 

For example, suppose you have the following program in memory: 

10 PRINT "THIS IS A TEST" 

20 INPUT "PRESS <ENTER> FOR THE NEXT PRINT MESSAGE"! Z$ 

30 A = A + 1 
40 PRINT "+++++++" 

CMD "X" > PRINT will find all occurrences of print, except for cases where 
print was part of a quoted string: lines 10 and 40. 

CMD " X"» "PRINT" will find all occurrences of ‘ ‘print’ ’ as a string literal: line 

20 . 

CMD "X", + will list line 30, but CMD "X" » " + " will list line 40. CMD "X"* 
"A" will list lines 10, 20, and 30. Notice that variables and text are both treated 
as string literals. 

y CMD “Z” 

Duplicate Output to Video and Printer 


CMD“Z”, “switch” 

switch is either on or off. switch must be enclosed in quotation marks. 


This command enables or disables dual video/printer output. While the function 
is “on,” all video output is copied to the printer, and all printer output is copied 
to the video. (The printer must be on-line when you turn dual output “on.”) 

Video and printer output may differ due to intrinsic differences in the printer and 
video devices. 

Examples 

CMD "Z"i "ON" 

Turns dual video/printer output on. 
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CMD"Z" i "OFF" 

TUms dual video/printer output off. 

DEFFN 
Define Function 


def fn function name (argument-1,...) = formula 

function name is any valid variable name. 

argument-1 and subsequent arguments are used in defining what the 
function does. 

formula is an expression usually involving the argument(s) passed on 
the left side of the equals sign. 


The deffn statement lets you create your own function. That is, you only 
have to call the new function by name, and the associated operations will 
automatically be performed. Once a function has been defined with the deffn 
statement, you can call it simply by inserting fn in front of function name. You 
can use it exactly as you might use one of the built-in functions, like sin, abs, 
and strings. 

The type of variable used for function name determines the type of value the 
function will return. For example, if Junction name is single precision, then that 
function will return a single-precision value, regardless of the precision of the 
arguments. 

The particular variables you use as arguments in the def fn statement 
(argument-1 , . . .) are not assigned to the function. When you call the function 
later, any variable name of the same type can be used. 

Furthermore, using a variable as an argument in a deffn statement has no effect 
on the value of that variable. So you can use that particular variable in another 
part of your program without worrying about interference from deffn. 

The function can be defined with no arguments at all, if none are required. 

For example: 

DEF FNR = RND (90) + 9 

defines a function to return a random value between 10 and 99. 
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Examples 

DEF FNR (A tB) = A + INK (B - (A - 1)) * RND (0)) 

This statement defines function fnr which returns a random number between 
integers A and B. The values for A and B are passed when the function is 
“called,” i.e., used in a statement like: 

Y = FNR1R1» R2) 

If Ri and R2 have been assigned the values 2 and 8, this line would assign a 
random number between 2 and 8 to y. 

DEF FNL*(X) = STRING$(X t 

Defines function fnl$ which returns a string of hyphens, x characters long. 

The value for x is passed when the function is called: 

PRINT FNL$(3) 

This line prints a string of 30 hyphens. 

Here’s an example showing def fn used for a complex computation—in 
double-precision. 

DEF FNX#(A#» B#) = (A# - B#) * (A# - B#) 

Defines function fnx# which returns the double-precision value of the square of 
the difference between a# and b#. The values for a# and b# are passed when 
the function is called: 

S# = FNX#(A# > B#) 

We assume that values for a# and b# were assigned elsewhere in the program. 

Sample Program 

710 DEF FNO(T) = (1087 + SQR(273 + T))/1G.52 
720 INPUT "AIR TEMPERATURE IN DEGREES CELSIUS"; T 
730 PRINT "THE SPEED OF SOUND IN AIR OF" T "DEGREES 
CELSIUS IS" FNV(T) "FEET PER SECOND♦" 
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DEFUSR 

Define Point of Entry for USR Routine 


defusr/7 = address 

n equals one of the digits 0,if n is omitted, 0 is assumed, address 
specifies the entry address to a machine-language routine, address 
must be in the range [ - 32768,32767]. address may be any numeric 
expression or constant from -32768 to 32767. 


defusr lets you define the entry points for up to 10 machine-language routines. 
In non-Disk basic, the addresses were POKEd into ram. This poke method 
cannot be used in Disk basic. 

Examples 

DEFUSR3 = &H7D00 

assigns the entry point x’7D00\ 32000 decimal, to the USR3 call. When your 
program calls USR3, control will branch to your subroutine beginning at X’7D00\ 

DEFUSR = (BASE + IS) 

assigns start address (base + 16) to the usro routine. 

Note: When decimal addresses are given, they are evaluated as signed two-byte 
integers. So, for addresses above 32767, use desired decimal address —65536. 
See usr/i. 


INSTR 

Search for Specified String 


instr (position, string 1, string 2) 

position specifies the position in string 1 where the search is to begin. 
position is optional; if it is not supplied, search automatically begins 
at the first character in string 1„ (Position 1 is the first character in 
string 1.) 
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string 1 is the string to be searched. 

string 2 is the substring you want to search for. 


This function lets you search through a string to see if it contains another string. 
If it does, instr returns the starting position of the substring in the target string; 
otherwise, zero is returned. Note that the entire substring must be contained in 
the search string, or zero is returned. Also, note that instr only finds the first 
occurrence of a substring at the position you specify. 


Examples 

In these examples, a$ = “Lincoln”: 

INSTR(A$ t "INC") 
returns a value of 2. 

INSTR (A$ i "12") 
returns a zero. 

INSTR(A$ t "LINCOLNABRAHAM") 

returns a zero. For a slightly different use of instr, look at 

INSTR (3 > "1232123" * "12") 

which returns 5. 


Sample Program 

This program gets search and target text from the keyboard, then locates all 
occurrences of the target text in the search text. Line 90 is just for “show.” 

10 CLEAR 1000 
20 CLS 

30 INPUT "SEARCH TEXT"5 S$ 

40 INPUT "TARGET TEXT"? T$ 

45 CLS 

50 C = 0 : P = 1 'P = POSITION» C = COUNT 
60 F = INSTR(P tS$ »T$) 

70 IF F = 0 THEN 120 
80 C = C + 1 

90 PRINT @0»LEFT$(S$ ,F-1) + STRING$(LEN(T$) >191) + 

'• RIGHT$(S$ tLEN( S$) - F-LEN (T$) + l) 

100 P = F + LEN(T$) 

110 IF P <= LEN(S$) - LEN(T$) + 1 THEN G0 
120 PRINT "FOUND "! Ci "OCCURRENCES" 
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LINE INPUT 

Input a Line from Keyboard 


line input “prompt” variable 

prompt is a prompting message. 

variable is the name that will be assigned to the line you type in. 


line input (or lineinput— the space is optional) is similar to input, except: 

• The Computer will not display a question mark when waiting for your 
operator’s input. 

• Each line input statement can assign a value to just one variable. 

• Commas and quotes your operator can use as part of the string input. 

• Leading blanks are not ignored—they become part of variable. 

• The only way to terminate the string input is to press [ENTER) . 

line input is a convenient way to input string data without having to worry 
about accidental entry of delimiters (commas, quotation marks, colons, etc.). 
The (ENTER) key serves as the only delimiter. If you want anyone to be able to 
input information into your program without special instructions, use the line 
input statement. 

Some situations require that you input commas, quotes and leading blanks as 
part of the data, line input serves well in such cases. 

Examples 

LINE INPUT A$ 

Input a$ without displaying any prompt. 

LINE INPUT "LAST NAME t FIRST NAME? "IN* 

Displays a prompt message and inputs data. Commas will not terminate the 
input string, as they would in an input statement. 

Sample Program 

200 REM CUSTOMER SURVEY 
205 CLEAR 1000 
207 PRINT 
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210 

220 

230 

235 

240 

250 

260 

270 


LINE INPUT "TYPE IN YOUR NAME "5 A$ 
LINE INPUT "DO YOU LIKE YOUR COMPUTER? 
LINE INPUT "WHY? "5 C$ 

PRINT 

PRINT A$ : 

IF B$ = "NO 


B$ 


PRINT 
THEN 270 

PRINT "I LIKE MY COMPUTER BECAUSE “5 C* :END 
PRINT "I DO NOT LIKE MY COMPUTER BECAUSE "! C$ 


Notice that when line 210 is executed, a question mark is not displayed after the 
statement, “Type in your name.” Also, notice on line 230 you can answer the 
question “Why” with a statement full of delimiters, commas and quotes. 


MID$ = 

Replace Portion of String 


mid$ (oldstring, position, length) = replacement-string 

oldstring is the variable-name of the string you want to change. 

position Is the numeric expression specifying the position of the first 
character to be changed. 

iength is a numeric expression specifying the number of characters to be 
replaced. 

replacement-string is a string expression to replace the specified portion 
of oldstring. 

Note: If replacement-string is shorter than length, then the entire replacement¬ 
string will be used. 


This statement lets you replace any part of a string with a specified new string, 
giving you a powerful string editing capability. 

Note that the length of the resultant string is always the same as the original 
string. 

Examples 

a$ = “Lincoln” in the examples below: 

MID$(A$ > 3 1 4) = "12345": PRINT A* 
which returns LI1234N. 
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MIDt(At t 1. 2) = H ": PRINT AS 
which returns Lincoln. 

MID$(A$ > 5) = "12345": PRINT A$ 
returns LINC123. 

MID$(A$» 5) = "01": PRINT A$ 
returns lincoin. 

MID$(A$» 1 * 3) = "***": PRINT A$ 
returns ***coln. 

Sample Program 

770 CLS: PRINT: PRINT 

790 LINE INPUT "TYPE IN A MONTH AND DAY MM/DD. "5 S$ 
790 P = INSTR(S$ t "/") 

800 IF P = 0 THEN 780 

810 MID$(S$ > P. 1) = CHR$(45) 

820 PRINT S$ " IS EASIER TO READ t ISN'T IT?" 

This program uses instr to search for the slash (“/”)- When it finds it 
(if it finds it), it uses mid$ = to substitute a “ — ” <chr$(45» for it. 


NAME 

Renumber the Current Program 


name newline, startline, increment 

newline specifies the new line number of the first line to be renumbered. 

If omitted, 10 is used. 

startline specifies the line number in the original program where 
renumbering will start. If omitted, the entire program will be 
renumbered. 

increment specifies the increment to be used between each successive line 
number. If omitted, 10 is used. 
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Examples 

NAME 

Renumbers the entire program: 10, 20, 30, .. . 

NAME B000 .5000#100 

Renumbers all lines numbered from 5000 up; the first renumbered line will 
become 6000, and the following lines will be incremented by 100. All line 
references within your program will be renumbered also. 


USRn 

Call to User’s External Subroutine 


usr n (nmexp) 


where n specifies one of ten available usr calls, n= 0,1,2.9. If n is 

omitted, zero is assumed. 


nmexp is an integer from -32768 to 32767 and is passed as an integer 
argument to the routine. 



These functions (usro through USR9) transfer control to machine-language 
routines previously defined with defusrw statements. 

When a urs call is encountered in a statement, control goes to the address 
specified in the defusrw statement. This address specifies the entry point to your 
machine-language routine. 

Note: If you call a usrw routine before defining the routine entry point with 
defusrw, an illegal function call error will occur. 

You can pass one argument and retrieve one output value directly via the usr 
argument; or you can pass and retrieve arguments indirectly via poke and peek 
statements. 

Example 

1.0 DEFUSR1=&H7D00 

20 REM...MORE PROGRAM LINES HERE 

100 A=USR1(X) 

The effect of this sequence is to: 


V 
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1. Define usr as a routine with an entry point at hex 7 D00 (line 10). 

2. Transfer control to the routine; the value x can be passed to the routine if the 
routine makes the call described below (line 100 ). 

3. When the routine returns to basic, the variable A may contain the value 
passed back from the routine (if your routine makes the jump described 
below); otherwise a will be assigned the value of x (line 100). 

Passing arguments to and from USR routines 

There are several ways to pass arguments back and forth between your basic 

main program and your usr routines: the two major ways are listed below. 

1. poke the argument(s) into fixed ram locations. The machine-language routine 
can then access these values and place results in other ram locations. When 
the routine returns control to basic, your program can peek into these 
addresses to pick up the “output” values. This is the only way to pass two 
or more arguments back and forth. 

2. Pass one argument to the routine as the argument in the usRn call, then use 
special rom calls to access this argument and return a value to basic. This 
method is limited to sending one argument and returning one value (both 
are integers). 

rom Calls 

call 0 A7FH Puts the usr argument into the hl register pair; h contains msb, l 
contains lsb. This call should be the first instruction in your usr 
routine. 

jp 0 A9AH Use this jump to return to basic; the integer in hl becomes the 
output of the usr call. If you don’t care about returning hl, then 
execute a simple RETum instruction instead of this jump. 

Listed below is an assembled program to white out the display (an “inverse” 

clear key!). Don’t type it in. Type in the basic program that follows it. 



00100 

5 





00110 

5 ZAP OUT 

SCREEN 

USR FUNCTION 



00120 

• 

i 




7D00 

00130 

00140 

5 

0RG 

7D00H 



00150 

5 EQUATES 





00160 

5 




3C00 

00170 

VIDEO 

EQU 

3C00H 

5START OF VIDEO RAM 

00BF 

00180 

WHITE 

EQU 

0BFH 

;all WHITE GRAPHICS 

03FF 

00190 

COUNT 

EQU 

3FFH 

5NUMBER OF BYTES TO 


00200 

5 





00210 

? PROGRAM 

CHAIN 

MOVES X'BF' INTO 

ALL OF VIDEO RAM 


00220 

5 
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7D00 21003C 

00230 ZAP 

LD 

HL,VIDEO 

5S0URCE ADDRESS 

7D03 3GBF 

00240 

LO 

(HL)*WHITE 

;PUT OUT 1ST BYTE 

7D05 11013C 

00250 

LD 

DEtVIDEO+1 

DESTINATION ADDRESS 

7D08 01FF03 

00280 

LD 

BC,COUNT 

DUMBER OF ITERATIONS 

7D0B EDB0 

00270 

LDIR 


5DO IT TO IT!!! 


00280 ; 




7D0D C9 

00280 

RET 


5RETURN TO BASIC 

7D00 

00300 

END 

ZAP 



This routine can be poKEd into ram and accessed as a usr routine. First start basic and answer the 
MEMORY SIZE question with 31939. Then run the program. 

100 ' PROGRAM: USR1 

110 ' EXAMPLE OF A USER MACHINE LANGUAGE FUNCTION 
115 ' DEPRESS THE '@' KEY WHILE NUMBERS ARE PRINTING TO STOP 
120 ' 

130 ' ******* POKE MACHINE PROGRAM INTO MEMORY ******* 

140 ' 

150 DEFUSR1 = 8.H7D00 

1G0 FOR X = 32000 TO 32013 '7D00 HEX EQUAL 32000 DECIMAL 

170 READ A 

180 POKE K» A 

190 NEXT X 

192 ' 

194 ' ******* CLEAR SCREEN 8c PRINT NUMBERS 1 THRU 100 ******* 

196 ' 

200 CLS 

205 PRINT TAB<15)5 "WHITE-OUT USER ROUTINE": PRINT 
210 FOR X = 1 TO 100 
220 PRINT X! 

225 A$ = INKEY$: IF A* = "8" THEN END 
230 NEXT X 
240 ' 

250 ' ******* JUMP TO WHITE-OUT SUBROUTINE ******* 

260 ' 

270 X = USR1 (0) 

280 FOR X = 1 TO 1000: NEXT X 'DELAY LOOP 
290 GOTO 200 
300 ' 

310 ' ******* DATA IS DECIMAL CODE FOR HEX PROGRAM ******* 

320 ' 

330 DATA 33»0»G0»54»191117 »1>60>1>255 13 >237 >176 >201 

Run the program. An equivalent basic white out routine takes a long time by comparison! 
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Disk-Related Features 

Disk basic provides a powerful set of commands, statements and functions 
relating to disk I/O under trsdos. These fall into two categories: 

1. File manipulation: dealing with files as units, rather than with the distinct 
records the files contain. 

2. File access: preparing data files for i/o; reading and writing to the files. 

Under the heading. File Manipulation, we will discuss the following 
commands. 

kill Delete a program or data file from the disk 

load Load a basic program from disk 

merge Merge an Ascii-format basic program on disk with one 

currently in ram 

run ‘ ‘program Load and execute a basic program stored on disk 
save Save the resident basic program on disk 

Under the heading. File Access, we will discuss the following statements and 
functions. 

Statements 

OPEN 
CLOSE 
INPUT# 

LINE INPUT# 

PRINT# 

FIELD 
GET 
PUT 
LSET 

RSET 

Functions 

CVD 

CVI 
CVS 

EOF 
LOC 


Open a file for access (create the file if necessary) 

Close access to the file 
Read from disk, sequential mode 
Read a line of data, sequential mode 
Write to disk, sequential mode 

Assign field sizes and names to random-access file buffer 
Read from disk, random access mode 
Write to disk, random access mode 

Place value in specified buffer field, add blanks on the 
right to fill field 

Place value in specified buffer field, add blanks on the left 
to fill field 

Restore double-precision number to numeric form after 
GETting from disk 

Restore integer to numeric form after GETting from disk 

Restore single-precision number to numeric form after 
GETting from disk 

Check to see if end of file encountered during read 
get current record number. 





116 






DISK BASIC 


LOF 

MKD$ 

MKI$ 

MKS$ 


Return number of last record in file 

Convert double-precision number to string so it can be put 
on disk 

Convert integer to string so it can be put on disk 
Convert single-precision number to string so it can be put 
on disk 
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File Manipulation 

KILL 

Delete a File from the Disk 


KILL exp$ 

exp$ defines a file specification for an existing file. 


This command works like the trsdos kill command—see trsdos Library 
Commands. 


Example 

KILL"0LDFILE/BAS.PSW1" 

deletes the file specified from the first drive which contains it. 

Do not kill an open file, or you may destroy the contents of the diskette. (First, 
close the open file.) 


LOAD 

Load BASIC Program File from Disk 


LOAD eX/7$[,R} 

where exp$ defines a filespec for a basic program file stored on disk. 
r tells basic to run the program after it is loaded. 


This command loads a basic program file into ram; if the R option is used, 
basic will proceed to run the program automatically; otherwise, basic will 
return to the command mode. 
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load without the R option clears all variables and closes all open files, load 
with the R option clears all variables but does not close the open files. 

load with the R option is equivalent to the command run exp$, R. Either of 
these commands can be used inside programs to allow program chaining — one 
program calling another, etc. 

Example 

LOAD"PROG1/BAS:2" 

Clears resident basic program and loads progi/bas from Drive 2; returns to 
basic command mode. 


MERGE 

Merge Disk Program with Resident Program 


MERGE exp$ 

expS is file specification for an Ascii-format basic disk file, e.g., a program 
saved with the A-option. 


merge is similar to load —except that the resident program is not erased before 
the new program exp$ is loaded. Instead, the new program is merged into the 
resident program. 

That is, program lines in exp$ will simply be inserted into the resident program 
in sequential order. If line numbers in exp$ coincide with line numbers in the 
resident program, the resident lines will be replaced by those from exp$. 
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Program on Disk Program In Ram Merged Program in Ram 


10 


10 


10 



20 


20 



30 


30 



40 


40 



50 


50 


+ 

60 


60 


l 

70 


70 

$0 


90 


90 

100 




100 

110 




110 

120 




120 


Sample Use 

Save this program in ascii format. 

1000 REM . . . SUBROUTINE TO SAY HELLO 
1010 PRINT "HELLO!" 

1020 RETURN 

Type NEW (ENTER) , then type in this program. 

100 CLS 

110 PRINT "LET'S CALL THE SUBROUTINE . , 

120 PRINT "DIALING NOW ..." 

130 FOR 1=1 TO 1000 : NEXT 
140 GOSUB 1000 

150 PRINT "BACK FROM SUBROUTINE." 

1S0 END 

Now type MERGE “file” using the file name given to the first file. List the program. Then run it. 



RUN 6 ‘program” 

Load and Execute a Program from Disk 


run file[,n] 

file is the name of a basic program file. It is a string expression. (If a string 
constant is used, it must be enclosed in quotes.) The ,r option causes 
basic to leave open files open. If omitted, open files are closed before 
the program is run. 
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w 1 ' 


This command loads and executes a basic program stored on disk. It may be 
used inside a program to allow chaining (one program calling another). 

Examples 

RUN "PROG" 

Loads and executes prog (all open files are closed first). 

A$ ="NEWPROG" 

RUN A$# R 

Loads and executes newprog (all open files remain open). 


SAVE 

Save Program onto Disk 


save file [,a] 

file is the name of a basic program file. It is a string expression. 

(If a string constant is used, it must be enclosed in quotes.) 

a causes the file to be stored in ascii rather than compressed format. 


This command lets you save your basic programs on disk. You can save the 
program in compressed or ascii format. 

Using compressed format takes up less disk space and is faster during both 
saves and loads. Using the Ascn option makes it possible to do certain things 
that cannot be done with compressed format basic files. 

For example: 

• The merge command requires that the disk file be in ascu form. 

• Programs which read in other programs as data will typically require that the 
data programs be stored in ascii. 

• The trsdos command append also requires that disk files be in ascii form. 
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Examples 

SAVE"FILE1/BAS. J0HN0D0E:3" 

saves the resident basic program in compressed format with the file name filei, 
extension /bas, password johnqdoe; the file is placed on Drive :3. 

SAVE"MATHPAK/TXT"»A 

saves the resident program in asco form, using the name mathpak/txt, on the 
first nonwrite-protected diskette. 

Upon completion of a save, basic returns in the command mode. 
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File Access 

This section is divided into four parts: 

1. Creating files and assigning buffers — open and close 

2. Statements and functions 

3. Sequential i/o techniques 

4. Random i/o techniques 

If this is your first experience with disk file access, you should concentrate on 
parts 1, 3 and 4, perhaps just skimming through part 2 to get a general idea of 
how the functions and statements work. Later you can go back to part 2 and 
learn the details of statement and function syntax. 

Creating Files and Assigning Buffers 

During the initialization dialog, you type in a number in response to how many 
files? The number you type in tells basic how many buffers to create to handle 
your disk accesses (reads and writes). 

Each buffer is given a number from 1 to 15. If you type: 

HOW MANY FILES? 30 (INTER) 

basic sets aside 3 buffers, numbered 1,2,3. 

You can think of a buffer as a waiting area that data must pass through on the 
way to and from the disk file. When you want to access a particular file, you 
must tell basic which buffer to use in accessing that file. You must also tell 
basic what kind of access you want—sequential output, sequential input, or 
random input/output. 

All this is done with the open statement, and “undone” with the close 
statement. 


OPEN 
Open a File 


open mode, buffer, file, record-length 

mode is a string expression containing one of the following: 

i Sequential input starting at the first record. If the file is not found, 
it will be created. 
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o Sequential output starting at the first record. If the file is not 
found, it will be created. 

e (Extend) Sequential output starting at end of file. If the file is not 
found, it will be created. 

r Random input/output. II the file is not found, it will be created. 

If mode is a constant, it must be enclosed in quotes. 

butter \s a numeric expression specifying which buffer is to be used. 

file is a string expression containing the file specification. If a constant is 
used, it must be enclosed in quotes. 

record-length is a numeric expression from 0 to 256 specifying the logical 
record length. 0 is the same as 256. This option may only be used if 
variable-length records were requested during initialization (How 
Many Files?). If record-length is omitted, 256 is used, record-length 
is used with Random access only. 




This statement lets you create a file, write data into it, update it, and read it. For 
details on file access, see Methods of Access later in this section. 

If file includes a drive specification, basic will use only the specified drive. If 
no drive is specified, basic will search for a matching file, starting with the 
master drive (usually Drive 0). 

Examples 

OPEN "0"# 1# "DATAFILE" 

Opens datafile (creates it if it doesn’t already exist) for sequential output. 
Output will be done through buffer #1. Records will be 256 bytes long. Since 
the “o” mode is specified, output will start at the first record in the file. 

If “e” is used instead of “o”, output will start at the end of the file. 

OPEN 11 R“ * 2* "PAYROLL/A: 1" * B4 

Opens/creates payroll/a for random input/output. Access will be through 
buffer #2. Records will be 64 bytes long (if basic was initialized for variable- 
length records). 

BUFFER = 3: FILE* = "DATA": RECLN = 128 
OPEN "R"* BUFFER* FILE** RECLN 

Opens/creates data for random input/output. Access will be through buffer #3. 
Records will be 128 bytes long (if basic was initialized for variable-length 
records). 
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CLOSE 

Close Access to the File 


close [nmexp [,nmexp ...] ] 

nmexp has a value from 1 to 15, and refers to the file’s buffer number 
(assigned when the file was opened). If nmexp is omitted, all open 
files will be closed. 


This command terminates access to a file through the specified buffer(s). 

If nmexp has not been assigned in a previous open statement, then 

close nmexp 

has no effect. 

Examples 

CLOSE 1 ,2,8 

Terminates the file assignments to buffers 1, 2 and 8. These buffers can now be 
assigned to other files with open statements. 

CLOSE FIRSmCOUNU 

Terminates the file assignment to the buffer specified by the sum 
(F1RST% + COUNT%). 

Do not remove a diskette which contains a file opened for writing (mode = O, 
E, or R). First close the file. This is because the last 256 bytes of data may not 
have been written to disk yet. Closing the file will write the data, if it hasn’t 
already been written. 

Any modification to the resident program (new, editing, load, merge, etc.) 
will cause open files to be closed. 
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INPUT# 

Sequential Read from Disk 


input# nmexp, var[,var.. .1 

where nmexp specifies a sequential input file buffer, nmexp= 1,2.15. 

raris the variable name to contain the data from the file. 


This statement inputs data from a disk file. The data is input sequentially. That 
is, when the file is first opened, a pointer is set to the beginning of the file. 

Each time data is input, the pointer advances. To start over reading from the 
beginning of the file, you must close the file and re-open it. 

input# doesn’t care how the data was placed on the disk—whether a single 
print# statement put it there, or whether it required 10 different print# 
statements. What matters to input# are the positions of the terminating 
characters and the eof marker. 

To input# data successfully from disk, you need to know ahead of time what 
the format of the data is. Here is a description of how input# interprets the 
various characters it encounters when reading data. 

When inputting data into a variable, basic ignores leading blanks; when the 
first non-blank character is encountered, basic assumes it has encountered the 
beginning of the data item. 

The data item ends when a terminating character is encountered or when a 
terminating condition occurs. The particular terminating characters vary, 
depending on whether basic is inputting to a numeric or string variable. 

Special Note 

Here’s an important exception to keep in mind in reading the following material. 

When (ENTER) (a carriage return) is preceded by ® (a line feed), the (ENTER) is 
not taken as a terminator. Instead, it becomes a part of the data item (string 
variable) or is simply ignored (numeric variable). 

(To enter the ® character from the keyboard, press the down-arrow character. 
To enter the (ENTER) character, press (ENTER) .) 

This exception applies to all cases noted below where (ENTER) is said to be a 
terminator. 
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Numeric Input 

Suppose the data image on disk is 
1.234 -33 27 (ENTER) 

(ENTER) denotes a carriage-return character (ascii code decimal 13). 

Then the statement 

INPUT#1» A.B.C 

or the sequence of statements 

INPUT#1»A: INPUT#1>B: INPUT#1>C 

will assign the values as follows: 

A =1.234 
B= -33 
C = 27 

This works because blanks and (ENTER) serve as terminators for input to numeric 
variables. The blank before 1.234 is a “leading blank,” therefore it is ignored. 
The blank after 1.234 is a terminator; therefore basic starts inputting the second 
variable at the - character, inputs the number -33, and takes the next two 
blanks as terminators. The third input begins at the 2 and ends with the 7. 

String Input 

When reading data into a string variable, input ignores all leading blanks; 
the first non-blank character is taken as the beginning of the data item. 

If this first character is a double-quote (“), then input will evaluate the data as 
a quoted string: it will read in all subsequent characters up to the next double¬ 
quote. Commas, blanks, and (ENTER) characters will be included in the string. 
The quotes themselves do not become a part of the string. 

If the first character of the string item is not a double-quote, then input will 
evaluate the data as an unquoted string: it will read in all subsequent characters 
up to the first comma, or (ENTER) . If double-quotes are encountered, they will be 
included in the string. 

For example, if the data on disk is: 

PECOS, TEXAS “GOOD MELONS” 

Then the statement 

INPUT#1» A$.B$,C$ 
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would assign values as follows: 

A$=PECOS 

B$= TEXAS “GOOD MELONS” 

C$ = null string 

If a comma is inserted in the data image before the first double quote, c$ will 
get the value, good melons. 

These are very simple examples just to give you an idea of how input works. 
However, there are many other ways to input data—different terminators, 
different target variable types, etc. 

Rather than taking a shotgun approach and trying to cover them all, we’ll give a 
generalized description of how input works and what the terminating characters 
and conditions are, and then provide several examples. 

When basic encounters a terminating character, it scans ahead to see how many 
more terminating characters it can include with the first terminator. This ensures 
that basic will begin looking for the next data item at the correct place. 

The list below defines the various terminating sets input# will look for. It will 
always try to take-in the largest set possible. 

Numeric-input terminator sets 

end of file encountered 
255th data character encountered 
,(comma) 

(ENTER) 

(ENTER) © 

[ . . .1 f (ENTER) ] 

[ . . .][ (ENTER) ©! 

Quoted-string terminator sets 

end of file encountered 
255th data character encountered 
“ (double quote) 

“[ •••][,] 

” [ . . .1T (ENTER) ! 

“ [ . . .If (ENTER) ©! 

Unquoted-string terminator sets 

end of file encountered 
255th data character encountered 

(ENTER) [©] 

Figure 13 describes how input# assigns data to a variable. 
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Figure 13. Input process. 

The following table shows how various data images will be read-in by the 
statement: 


INPUT#1»A»B»C 


Ex.# 

Image on disk 

Values 

assigned 

1 

123.45 (INTERIM B.2E4 7000(ENTER) 

A = 123.45 

B = 82000 

C = 7000 

2 

3(^)(ENTER) a CENTERS (ENTER) A12eof 

CO if) o 
II II II 

< CD O 

3 

1 » i2 >3 id (ENTER) 

1- O CM 

11 II II 

< CD O 

4 

l >3 > eof 

A = 1 

B = 3 

C = 0 eof error 


(eof = end of file): 

In Example 2 above, why does variable c get the value 0? When the input 
reaches the end of file, it terminates that last data item, which then contains 
“A12.” This is evaluated by a routine just like the basic val function — which 
returns a zero since the first character of “ai2” is a non-numeric. 
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In Example 3, when input# goes looking for the second data item, it 
immediately encounters a terminator (the comma); therefore, variable B is given 
the value zero. 

The following table shows how various data images on disk will be read by the 
statement: 

INPUT#1»A$»B$ 


Ex.# 

Image on disk 

Values assigned 

1 

"ROBERTS»J."ROBERTS,M.N eof 

A$:ROBERTS,J. 

B$:ROBERTS,M.N. 

2 

ROBERTS »J. > ROBERTS »M.N. (ENTER) 

A$:ROBERTS 

B$:J. 

3 

THE WORD "QUO" (12345.789 (ENTER) 

A$:THE WORD “QUO” 
B$:12345.789 

4 

BYTE® (ENTER) UNIT OF MEMORY eof 

A$:BYTE©(ENTER) 

UNIT OF MEMORY 
B$:null (eof error) 


In Example 3, the first data item is an unquoted string, therefore, the double¬ 
quotes are not terminators, and become part of a$. 

In Example 4, the (ENTER) is preceded by an ®, therefore it does not terminate 
the first string; both © and (ENTER) are included in A$. 


LINE INPUT# 

Read a Line of Text from Disk 


LINE INPUT#/WJM/J, V8f$ 

where nmexp specifies a sequential output file buffer, nmexp=‘\,2 .15. 

var$ is the variable name to contain the string data. 


Similar to line input from keyboard, this statement reads a “line” of string 
data into var$. This is useful when you want to read an Ascn-format basic 
program file as data, or when you want to read in data without following the 
usual restrictions regarding leading characters and terminators. 
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line input (or lineinput —the space is optional) reads everything from the first 
character up to: 

1. an (ENTER) character which is not preceded by ® 

2. the end of file 

3. the 255th data character (this 255 character is included in the string) 

Other characters encountered—quotes, commas, leading blanks, © (ENTER) 
pairs—are included in the string. 

For example, if the data looks like: 

10 CLEAR 500 (ENTER) 

20 OPEN" I" *1 t"PR0G" (1NTEH) 

♦ 

* 

* 

then the statement 
LINEINPUT#1>A$ 

could be used repetitively to read each program line, one line at a time. 



PRINT# 

Sequential Write to Disk File 


print# nmexp, [using formats ;J exfip exp ...] 

where nmexp specifies a sequential output file buffer, /?/nexp=1,2,...,15. 

formats is a sequence of field specifiers used with the using option. 

p is a delimiter placed between every two expressions to be PRiNTed to disk; 
either a semi-colon or comma can be used (semi-colon is preferable). 

exp is the expression to be evaluated and written to disk. 


This statement writes data sequentially to the specified file. When you first open 
a file for sequential output, a pointer is set to the beginning of the file, therefore 
your first print# places data at the beginning of the file. At the end of each 
print# operation, the pointer advances, so the values are written in sequence. 


vj 
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A print# statement creates a disk image similar to what a print to display 
creates on the screen. Remember this, and you’ll be able to set up your print# 
list correctly for access by one or more input statements. 

print# does not compress the data before writing it to disk; it writes an ascii- 
coded image of the data. 

For example, if A = 123.45 

PRINT#1 .A 

will write a nine-byte character sequence onto disk: 

123. 45 (INTER) 

The punctuation in the print list is very important. Unquoted commas and semi¬ 
colons have the same effect as they do in regular print to display statements. 

For example, if A = 2300 and b = 1.303, then 

PRINT#1#A »B 

places the data on disk as 

2300 1.303 INTER) 

The comma between a and b in the print# list causes 10 extra spaces in the 
disk file. Generally you wouldn’t want to use up disk space this way, so you 
should use semi-colons instead of commas. 

PRINT#1»A!B 

writes the data as: 

2300 1.303 (ENTER) 

print# with numeric data is quite straightforward—just remember to separate 
the items with semi-colons. 

print# with string data requires more care, primarily because you have to insert 
delimiters so the data can be read back correctly. In particular, you must 
separate string items with explicit delimiters if you want to input# them as 
distinct strings. 

For example, suppose: 

A$ ="JOHN 0. DOE" and B$ = " 100-01-001" 

♦ 

Then: 

PRINT#1. A$iB$ 

would produce this image on disk: 

JOHN 0. DOE100-01-001 (INTER) 

which could not be input back into two variables. 

The statement: 
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PRINT#1» A$5"»"!B$ 
would produce: 

JOHN 0. DOE i 100-01-001 

which could be input# back into two variables. 

This method is adequate if the string data contains no delimiters — commas or 
(ENTER) — characters. But if the data does contain delimiters or leading blanks 
that you don’t want to ignore, then you must supply explicit quotes to be written 
along with the data. For example, suppose A$ = " DOE ( JOHN 0." andB$="100 
- 01 - 001 " 

If you use 

PR INT#1 iA$ 5"»"5B$ 
the disk image will be: 

DOE > JOHN O,tl00-01-001 (ENTER) 

When you try to input this with a statement like 
INPUT#2(A$(B$ 

a$ will get the value doe, and b$ will get John q. —because of the comma after 
doe in the disk image. 

To write this data so that it can be input correctly, you must use the chr$ 
function to insert explicit double quotes into the disk image. Since 34 is the 
decimal ascii code for double quotes, use chr$( 34 ) as follows: 

PRINT#1(CHR*(34);A$!CHR$(3a)iBt 

this produces the disk image 

"DOE ( JOHN 0, "100-01-001 (INTER) 

which can be read with a simple 

INPUT#2(A$B$ 

Note: You can also use the chr$ function to insert other delimiters and control 
codes into the file, for example: 

chr$(io) © Line Feed 

chr$( 13 ) ,, carriage return ( (ENTER) character) 

chr$( 11 > or chr$( 12 ) line-printer top-of-form 

USING Option 

This option makes it easy to write files in a carefully controlled format. 

For example, suppose: 


A$="LUDWIG 
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B$="VAN" 

C$="BEETHOUEN" 

Then the statement 

PRINT#1 .USING"! . !. 1 l" ;A$»B$!C$ 
would write the data in nickname form: 

L.V.BEET <ENTER> 

(In this case, we didn’t want to add any explicit delimiters.) See the print using 
description in the level u basic Reference Manual for a complete explanation of 
the field-specifiers. 


Random Access Statements 


FIELD 

Organize a Random File-Buffer into Fields 


field nmexp, nmexpl *svar1$[,nmexp2 as var2 $...] 

nmexp specifies a random access file buffer, nmexp='\,2,...,15. 

nmexpl specifies the length of the first field. 

var1$ defines a variable name for the first field. 

nmexp2 specifies the length of the second field. 

var2$ defines a variable name for the second field. 

... Subsequent nmexp as var$ pairs define other fields in the buffer. 

Note: The sum of all the field-lengths must not exceed the record length, and 
should equal the record length. 


* 


Before field ing a buffer, you must use an open statement to assign that buffer 
to a particular disk file (you must use random access mode). Then use the held 
statement to organize a random file buffer so that you can pass data from basic 
to disk storage and vice-versa. 


Each random file buffer has up to 256 bytes which can store data for transfer 
from disk storage to basic or from basic to disk. (When variable-length files are 
used, maximum may be from 1 to 256.) However, you need a way to access this 
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buffer from basic so that you can either read the data it contains or place new 
data in it. The held statement provides the means of access. 

You may use the field statement any number of times to “re-organize” a file 
buffer. FiELDing a buffer does not clear the contents of the buffer; only the 
means of accessing the buffer (the field names) are changed. Furthermore, two 
or more field names can reference the same area of the buffer. 

Examples 

FIELD 1» 128 AS AS* 128 AS BS 

This statement tells basic to assign the first 128 bytes of the buffer to the string 
variable a$ and the remaining 128 bytes to b$. If you now print a$ and b$, you 
will see the contents of the buffer. Of course, this value would be meaningless 
unless you have used get to read a 256-byte record from disk. 

Note: All data—both strings and numbers—must be placed into the buffer in 
string form. There are three pairs of functions (mki$/cvi,mks$/cvs,mkd$/cvd) 
for converting numbers to strings and vice-versa. See “Functions” below. 

FIELD 3* 18 AS NMS > 25 AS ADS > 10 AS CYS» 2 AS STS>7 AS ZPS 

The first 16 bytes of buffer 3 are assigned the buffer name nm$; the next 25, 
ad$; the next 10, cy$; the next 2, st$ and the next 7, zp$. The remaining 196 
bytes of the buffer are not fielded at all. 

More on field names 

Field names, like nm$,ad$,cy$,st$, and zp$, are not string variables in the 
ordinary sense. They do not consume the string space available to basic. 

Instead, they point to the buffer field which you assigned with the field 
statement. That’s why you can use: 

100 FIELD 1>255 AS AS 

without worrying about whether 255 bytes of string space are available for as. 

If you use a buffer field name on the left side of an ordinary assignment 
statement, that name will no longer point to the buffer field; therefore, you 
won’t be able to access that field using the previous field name. 

For example, 

AS = B$ 

nullifies the effect of the field statement above (line 100). 

During random input, the get statement places data into the 255-byte buffer, 
where it can be accessed using the field names assigned to that buffer. During 
random output, lset and rset place data into the buffer, so you can then put 
the buffer contents into a disk file. 
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Often you’ll want to use a dummy variable in a field statement to “pass 
over” a portion of the buffer and start fielding it somewhere in the middle. 

For example: 

FIELD 1. 1G AS CLIENT*(1> » 112 AS HIST*(1) 

FIELD 1. 128 AS DUMMY*. IS AS CLIENT$(2). 112 AS HIST*(2) 

In the second field statement, dummy* serves to move the starting position of 
client$(2) to position 129. In this manner, two identical “subrecords” are 
defined on buffer number 1. We won’t actually use dummy* to place data into 
the buffer or retrieve it from the buffer. 

The buffer now looks like this: 


16 

112 

16 

112 

CL$ 

HIST$ 

CL$ 

HIST$ 

(D 

(1) 

(2) 

(2) 


DUMMY$ 




GET 

Read a Record from Disk—Random Access 


get nmexp1[,nmexp2\ 

nmexpl specifies a random access file buffer, nmexpl- 1,2,....,15. 

nmexp2 specifies which record to get in the file; if omitted, the current 
record will be read. 


This statement gets a data record from a disk file and places it in the specified 
buffer. Before GETting data from a file, you must open the file and assign a 
buffer to it. That is, a statement like: 

open “R” ,nmexpl ,filespec 

is required before the statement: 

get nmexpl,nmexpl 

get tells basic to read record nmexp2 from the file and place it into the nmexpl 
buffer. If you omit the record number in get, basic will read the current record. 
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The “current record’ is the record whose number is one higher than that of the 


last record accessed. The first time you 
current record is set equal to 1. 

For example: 

Program statement 

1000 OPEN“R”,l,“NAME/BAS” 

1010 FIELD 1,... 

1020 GET 1 

1025 REM...ACCESS BUFFER 
1030 GET 1,30 

1035 REM...ACCESS BUFFER 
1040 GET 1,25 

1046 REM...ACCESS BUFFER 
1050 GET1 


access a file via a particular buffer, the 


Effect _ 

Open name/bas for random access 
using buffer 1 

Structure buffer 

get record 1 into buffer 1 

get record 30 into buffer 1 

get record 25 into buffer 1 

get record 26 into buffer 1 


If you are using variable-length records (not fixed-length), an attempt to get 
past the end of file will produce an error. 

If you are using fixed-length records, the same attempt will return a null record 
and no error will occur. To prevent this from occurring, you can use the lof 
function to determine the number of the highest numbered record. 


PUT 

Write a Record to Disk—Random Access 


put nmexp1[,nmexp2\ 

nmexpl specifies a random access file buffer, rtm@jrp=1,2,...,15. 

nmexp2 specifies the record number in the file, nmexp2 is the record you 
want to write. If nmexp2 is omitted, the current record number is 
assumed. 


This statement moves data from a file’s buffer into a specified place in the file. 
Before PUTting data in a file, you must: 

1 . open the file, thereby assigning a buffer and defining the access mode (must 
beR); 
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2 . field the buffer, so you can 

3. place data into the buffer with lset and rset statements. 

When basic encounters the statement: 

put nmexp,nmexp2 
it does the following: 

• Gets the infonnation needed to access the disk file 

• Checks the access mode for this buffer (must be r) 

• Acquires more disk space for the file if necessary to accommodate the record 
indicated by nmexp2 

• Copies the buffer contents into the specified record of the disk file 

• Updates the current record number to equal nmexp2 + 1 

The “current record” is the record whose number is one higher than the last 
record accessed. The first time you access a file via a particular buffer, the 
current record is set equal to 1. 

If the record number you put is higher than the end-of-file record number, then 
nmexp2 becomes the new end-of-file record number. 



LSET and RSET 

Place Data in a Random Buffer Field 


lset var$ = exp$ and rset var$= expS 
var$ is a field name. 

exp$ contains the data to be placed in the buffer field named by var$. 


These two statements let you place character-string data into fields previously 
set up by a held statement. 

For example, suppose nm$ and ad$ have been defined as field names for a 
random file buffer. nm$ has a length of 18 characters, and ad$ has a length of 
25 characters. 

Now we want to place the following information into the buffer fields so it can 
be written to disk: 
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name: JIM CRICKET, JR, 

address: 2000 EAST PECAN ST. 

This is accomplished with the two statements: 

LSET NM$ ="JIM CRICKET,JR. " 

LSET AD$="2000 EAST PECAN ST. " 

This puts the data in the buffer as follows: 


Note that filler spaces were placed to the right of the data strings in both cases. 
If we had used rset instead of lset statements, the filler spaces would have 
been placed on the left. This is the only difference between lset and rset. 

For example: 

RSET NM$="JIM CRICKET,JR. " 

RSET AD$="2000 EAST PECAN ST. 

places data in the fields as follows: 

JIM CRICKET,JR. 

NM$ 

If a string item is too large to fit in the specified buffer field, it is always 
truncated on the right. That is, the extra characters on the right are ignored. 

CVD, CVI and CVS 
Restore String to Numeric Form 


ii 


2000 EAST PECAN ST. 
AD$ 


2000 EAST PECAN ST, 
AD$ 


JIM CRICKET,JR, 
NM$ 


cvd (exp$) 

exp$ defines an eight-character string; exp$ is typically the name of a 
buffer field containing a numeric string. If itu(exp$)<i, an illegal 
function call error occurs; if VEH(exp$)>6, only the first eight 
characters are used. 

m(exp$) 

exp$ defines a two-character string; exp$ is typically the name of a buffer 
field containing a numeric string. If \x.H(exp$)<2, an illegal function 
call error occurs; if v.in(exp$)>2, only the first two characters are 
used. 
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cvs (exp$) 

exp$ defines a four-character string; exp$ is typically the name of a buffer 
field containing a numeric string. If itn(exp$)<4, an illegal function 
call error occurs; if i£tt(exp$)>4, only the first four characters are 
used. 


These functions let you restore data to numeric form after it is read from disk. 
Typically the data has been read by a get statement, and is stored in a random- 
access file buffer. 

The functions cvd, cvi, and cvs are inverses of mkd$, mki$, and mks$, 
respectively. 

For example, suppose the name grosspays references an eight-byte field in 
a random-access file buffer, and after GETting a record, grosspays contains a 
mkd$ representation of the number 13123.38. 

Then the statement: 

PRINT CMD(GRQSSPAYt)-TAXES 

prints the result of the difference, 13123.38 — taxes. Whereas the statement: 
PRINT GROSSPAYt-TAXES 

will produce a type mismatch error, since string values cannot be used in 
arithmetic expressions. 

Using the same example, the statement 

A#=C0D<GR0SSPAYt) 

assigns the numeric value 13123.38 to the double-precision variable a#. 



EOF 

End-Of-File Detector 


eof (nmexp) 

nmexp specifies a file buffer, /»/nejrp=1,2,...,15. 
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This function checks to see whether all characters up to the end-of-file marker 
have been accessed, so you can avoid input past end errors during sequential 
input. 

Assuming nmexp specifies an open file, then eof( nmexp) returns 0 (false) when 
the eof record has not yet been read, and - 1 (true) when it has been read. 

Examples 

IF E0F(5) THEN PRINT"END OF FILE"FILENM$ 

IF EOF(NMX) THEN CLOSE NM2 

The following sequence of lines reads numeric data from data/txt into the 
array a( ). When the last data character in the file is read, the eof test in line 
30 “passes,” so the program branches out of the disk access loop, preventing 
an input past end error from occurring. Also note that the variable i contains 
the number of elements input into array a( ). 

5 DIM A(100) 'ASSUMING THIS IS A SAFE VALUE 
10 OPEN " I" 11 » "DATA/TXT" 

20 12=0 

30 IF EOF(1) THEN 70 
40 INPUT#1>A(12) 

50 12=12+1 
S0 GOTO 30 

70 REM PROGRAM CONTINUES HERE AFTER DISK INPUT 

LOC 

Get Current Record Number 


loc (file number) 

file number is a numeric expression specifying the buffer for a currentiy- 
open file. 


loc is used to determine the current record number, i.e., the number of the last 
record read since the file was opened, loc is only valid after a get. 

Example 


PRINT LOC(1) 
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Sample Program 

1310 A* = "WILLIAM WILSON" 

1320 GET 1> X: X = X+1 

1330 IF N$ = A$ THEN PRINT "FOUND IN RECORD" LOC(l): CLOSE: 
END 

1340 GOTO 1320 

This is a portion of a program. Elsewhere the file has been opened and fielded. 
N$ is a field variable. If n$ matches a$ the record number in which it was found 
is printed. 


LOF 

Get End-Of-File Record Number 


LdF(nmexp) 

nmexp specifies a random access buffer /i/nexp=1,2,.,.,15. 


This function tells you the number of the last, i.e., highest numbered, record 
in a file. It is useful for both sequential and random access. 

For example, during random access to a pre-existing file, you often need a 
way to know when you’ve read the last valid record, lof provides a way. 

lof is valid as soon as a previously created file is opened. If a file is extended, 
lof is not valid until a get is executed. 


Examples: 

10 OPEN "R",l > "UNKNOWN/TXT" 

20 FIELD 1>255 AS A$ 

30 F0RIX=1 TO LOF(1) 

40 GET 1 >H, 

50 PRINT A$ 

G0 NEXT 

In line 30, lof(1) specifies the highest record number to be accessed. 

Note: If you attempt to get record numbers beyond the end-of-file record, basic 
simply fills the buffer with hexadecimal zeros, and no error is generated. 
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When you want to add to the end of a file, lof tells you where to start adding: 

100 I2=L0F(1)+l 'HIGHEST EXISTING RECORD 
110 PUT 1#1% 'ADD NEXT RECORD 


MKD$, MKI$, and MKS$ 
Convert Data, Numeric-to-String 



mos(nmexp) 

nmexp is evaluated as a double-precision number. 
ma(nmexp) 

nmexp Is evaluated as an integer, — 32768< = /»mexp<32768; if nmexp 
exceeds this range, an illegal function call error occurs. Any 
fractional component in nmexp is truncated. 

mkss (nmexp) 

nmexp is evaluated as a single-precision number. 


These functions change a number to a “string.” Actually the byte values which 
make up the number are not changed; only one byte, the internal data-type 
specifier, is changed, so that numeric data can be placed in a string variable. 

That is: 

mkd$ returns an eight-byte string. 
mki$ returns a two-byte string. 
mks$ returns a four-byte string. 


Examples 

LSET TALLY$=MKI$(IX) 

Field name tally$ would now contain a two-byte representation of the 
integer i%. 

A$ = MKI $(8/I) 
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a$ becomes a two-byte representation of the integer portion of 8 / 1 . Any 
fractional portion is ignored. Note that a$ in this case is a normal string 
variable, not a buffer-field name. 


Suppose baseball/bat (a non-standard file extension) has been opened for 
random access using buffer 2, and the buffer has been FiELDed as follows: 

field: NM$ YRS$ AVG$ HR$ AB$ ERNINGS 

length: 16 2 4 2 4 4 

nm$ is intended to hold a character string; avg$, ab$ and ernings, converted 
single-precision values; yrs$ and hr$, converted integers. 

Suppose we want to write the following data record: 

slow learner played 38 years; lifetime batting average .123; 
career homeruns, 11; at bats, 32768;...,earnings - 13.75. 

Then we’d use the make-string functions as follows: 


1000 LSET 
1010 LSET 
1020 LSET 
1030 LSET 
1040 LSET 
1050 LSET 


NM$="SL0W LEARNER" 
YRS$=MK1$(38) 
AVG$=MKS$(.123) 

HR$ = MK1$(11) 

AB$=MKS$(327S8) 
ERNING$=MKS*(-13.75> 


After this sequence, you can write slow learner’s information to disk with 
the put statement. When you read it back from disk with get, you will need 
to restore the numeric data from string to numeric form, using cvi and cvs 
functions. 
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Methods of Access 

Disk basic provides two means of file access: 

• Sequential — in which you start reading or writing data at the beginning of 
a file; subsequent reads or writes are done at following positions in the file. 

• Random—in which you start reading or writing at any record you specify. 
(Random access is also called direct access.) 

Sequential access is stream-oriented; that is, the number of characters read or 
written can vary, and is usually determined by delimiters in the data. Random 
access is record-oriented; that is, data is always read or written in fixed-length 
blocks called records. 

To do any input/output to a disk file, you must first open the file. When you 
open the file, you specify what kind of access you want: 

• o for sequential output 

• i for sequential input 

• R for random input/output 

• e (Extend) for sequential output starting at the end of file. 

You also assign a file buffer for basic to use during file accesses. This number 
can be from 1 to 15, but must not exceed the number of concurrent files you 
requested when you started basic from trsdos. For example, if you started 
basic with 3 files, you can use buffer numbers 1,2, and 3. Once you assign a 
buffer number to a file, you cannot assign that number to another file until you 
Close the first file. 

Examples 

OPEN "0"> 1» "TEST" 

Creates a sequential output file named test on the first available drive; if test 
already exists, its previous contents are lost. Buffer 1 will be used for this file. 

OPEN "I"* 2* "TEST" 

Opens test for sequential input, using buffer 2. 

OPEN "R"» 1, "TEST" 

Opens test for direct access, using buffer 1. If test does not exist, it will be 
created on the first available drive. Since record length is not specified, 256-byte 
records will be used. 

OPEN "R", 1, "TEST"» 40 

Same as preceding example, but 40-byte records will be used. 

OPEN "E"» 1, "TEST" 

Opens test sequentially for write and positions to eof. 
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Sequential Access 

This is the simplest way to store data in and retrieve it from a file. It is ideal for 

storing free-form data without wasting space between data items. You read the 

items back in the same order in which they were written. 

There are several important points to keep in mind. 

1. You must start writing at the beginning of the file. If the data you are seeking 
is somewhere inside, you have to read your way up to it. 

2. Each time you Open a file for sequential output, the file’s previous contents 
are lost, unless you use “E” instead of “O” for the mode. 

3. To update (change) a sequential file, read in the file and write out the updated 
data to a new output file. 

4. Data written sequentially usually includes delimiters (markers) to signify 
where each data item begins and ends. To read a file sequentially, you must 
know ahead of time the format of the data. For example: Does the file consist 
of lines of text terminated with carriage returns? Does it consist of numbers 
separated by blank spaces? Does it consist of alternating text and numeric 
information? 

5. Sequential files are always written as Ascii-coded text, one byte for each 
character of data. For example, the number: 

1.2345 

requires 8 bytes of disk storage, including the leading and trailing blanks that 
are supplied. The text string: 

JOHNSON. ROBERT 

requires 15 bytes of disk storage. 

6. Sequential files are always written with a record length of 256. 

Sequential Output: An Example 

Suppose we want to store a table of English-to-metric conversion constants: 


English unit 

Metric equivalent 

1 inch 

1 mile 
t- acre 

1 cubic inch 

1 U.S. gallon 

1 liquid quart 

1 lb (avoir) 

2.54001 centimeters 

1.60935 kilometers 
4046.86 sq. meters 
0.01638716 liter 

3.785 liters 

0.9463 liter 

0.45359 kilogram 
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First we decide what the data image is going to be. Let’s say we want it to look 
like this: 

english unit t metric unit, factor (ENTER) 

For example, the stored data would start out: 

IN->CM > 2.54001 (ENTER) 

The following program will create such a data file. 

Note: X’OD’ represents a carriage return. 

10 OPEN "0" ,1 ."METRIC/TXT" 

20 FOR H, = 1 TO 7 
30 READ UNITS » FACTR 

40 PRINT#1. UNITf! "."5 FACTR 

50 NEXT 
60 CLOSE 

70 DATA IN->CM» 2.54001. MI->KM. 1.60935. ACRE->SQ.KM, 
4046.86 E-6 

80 DATA CU.IN->LTR. 1.638716E-2. GAL->LTR. 3.785 
90 DATA LIQ,QT->LTR. 0,9463. LB->KG. 0.45359 

Line 10 creates a disk file named metric/txt, and assigns buffer 1 for sequential 
output to that file. The extension /txt is used because sequential output always 
stores the data as Ascii-coded text. 

Note: If metric/txt already exists, line 10 will cause all its data to be lost. 
Here’s why: Whenever a file is opened for sequential output, the end-of-file 
(eof) is set to the beginning of the file. In effect, trsdos “forgets” that 
anything has ever been written beyond this point. To avoid this, you could use e 
instead of o in line 10. 

Line 40 prints the current contents of units and factr to the file. Since the 
spring items do not contain delimiters, it is not necessary to print explicit quotes 
around them. The explicit comma is sufficient. 

Line 60 closes the file. The eof is at the end of the last data item, i.e., 0.45359, 
so that later, during input, basic will know when it has read all the data. 


Sequential Input: An Example 

The following program reads the data from metric/txt into two “parallel” 
arrays, then asks you to enter a conversion problem. 

5 CLEAR 500 

10 DIM UNIT$(9) , FACTRO) 'allows for up to 10 data pairs 
20 OPEN"I".1 ,"METRIC/TXT" 

25 IX = 0 

30 IF EOF(1) THEN 70 
40 INPUT#1» UN ITt<IX) .FACTR(IX) 
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50 ix=ix+i 

G0 GOT.O 30 


70 

CLOSE 

' Conversion 

facto 

rs 

have been 

r e a d - i n 

100 

CLS: 

PRINT TAB(5)"*** 

En 31 i 

sh 

to Metric 

Conversions ***" 

110 

FOR I 

TEMX=0 TO IZ-1 





120 

PR 

INT TAB(9)5USING 

“ (ft* ) 


1 

1 M 5 ITEM It 


UNIT* 

(ITEM*,) 





130 

NEXT 






140 

PRINT 

@ 704# “Which c 

onvers 

ion 

(0-6)" ; 



150 INPUT CHOICE* 

160 INPUT“Enter English quantity"^ 

170 PRI NT"The Metric equivalent is" V*FACTR<CHOICEX) 

180 INPUT"Press <ENTER> to continue" 5X 

190 PRINT @ 704» CHR$(31) 'clear to end of frame 

200 GOTO 140 

Line 20 opens the file for sequential input. Input begins at the beginning of 
the file. 

Line 30 checks to see that the end-of-file record hasn’t been reached. If it has, 
control branches from the disk input loop to the part of the program that uses 
the newly acquired data. 

Line 40 reads a value into the string array unit$( ), and a number into the 
single-precision array factr( ). Note that this input list parallels the print# list 
that created the data file (see the section “Sequential Output: An Example”). 
This parallelism is not required, however. We could just as successfully have 
used: 

40 INPUT#1 i UNIT$(IX): INPUT#1»FACTR(IX) 


How to update a file 

Suppose you want to add more entries into the English-Metric conversion file. 
You could simply re-Open the file with mode = e and print# the extra data. 
Or, you might want to leave the old file intact and output a new file: 

1. Open the file for sequential input (Mode = i) 

2. Open another new data file for sequential output (Mode = o) 

3. Input a block of data and update the data as necessary 

4. Output the data to the new file 

5. Repeat steps 3 and 4 until all data has been read, updated, and output to the 
new file; then go to step 6 

6. Close both files 
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Sequential Line Input: An Example 

Using the line-oriented input, you can write programs that edit other basic 
program files: renumber them, change lprints to prints, etc. — as long as these 
“target” programs are stored in ascii format. 

The following program counts the number of lines in any ascii —format basic 
disk file with the extension /txt. 

10 CLEAR 300 

20 INPUT"WHAT IS THE NAME OF THE PROGRAM"5 PROG* 

30 IF INSTR(PROG$t"/TXT")=0 THEN 110 'require /TXT extension 
40 OPEN"I "> 1 , PROG* 

50 I%=0 

60 IF EOF(1) THEN 90 

70 n,= n, + l: LINE INPUT#1 » TEMP* 

80 GOTO 60 

90 PRINT PROG*" IS" 1% "LINES LONG." 

100 CLOSE: GOTO 20 

110 PRINT "FILESPEC MUST INCLUDE THE EXTENSION '/TXT'" 

120 GOTO 20 

For basic programs stored in ascii, each program line ends with a carriage 
return character not preceded by a line feed. So the line input in line 70 
automatically reads one entire line at a time, into the variable temps. Variable 
1% actually does the counting. 

To try out the program, first save any basic program using the a (ascii) option 
(See save). Use the extension /txt. 
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Random Access Techniques 

Random access offers several advantages over sequential access: 

• Instead of having to start reading at the beginning of a file, you can read any 
record you specify. 

• To update a file, you don’t have to read in the entire file, update the data, and 
write it out again. You can rewrite or add to any record you choose, without 
having to go through any of the other records. 

• Random access is more efficient—data takes up less space and is read and 
written faster. 

• Opening a file for direct access allows you to write and read from the file via 
the same buffer. 

• Random access provides many powerful statements and functions to structure 
your data. Once you have set up the structure, direct input/output becomes 
quite simple. 

The last advantage listed above is also the “hard part” of direct access. It takes 
a little extra thought. 

For the purposes of direct access, you can think of a disk file as a set of boxes 
— like a wall of post-office boxes. Just like the post office receptacles, the file 
boxes are numbered. We call these boxes “records.” 

You can place data in any record, or read the contents of any record, with 
statements like: 

PUT 1 >5 write buffer-1 contents to record 5 
GET 1 >5 read the contents of record 5 into buffer-1 

In Figure 14, we assume a record length of 256. 
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RECORDS IN DISK FILE 
Figure 14 . get and put. 
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The buffer is a waiting area for the data. Before writing data to a file, you must 
place it in the buffer assigned to the file. After reading data from a file, you 
must retrieve it from the buffer. 

As you can see from the sample put and get statements above, data is passed to 
and from the disk in records. The size of each record is determined by an Open 
statement. 

Storing Data in a Buffer 

You must place the entire record into the buffer before putting its contents into 
the disk file. 

This is accomplished by 1) dividing the buffer up into fields and naming them, 
then 2) placing the string or numeric data into the fields. 

For example, suppose we want to store a glossary on disk. Each record will 
consist of a word followed by its definition. We start with: 

100 0PEN"R"* It "GLOSSARY/BAS" 

110 FIELD It IB AS WD$t 240 AS MEANINGS 

Line 100 opens a file named glossary/bas (creates it if it doesn’t already exist); 
and gives buffer 1 direct access to the file. 

Line 110 defines two fields onto buffer 1: 

wd$ consists of the first 16 bytes of the buffer; 
meanings consists of the last 240 bytes. 

wd$ and meanings are now field-names 

What makes field names different? Most string variables point to an area in 
memory called the string space. This is where the value of the string is stored. 

Field names, on the other hand, point to the buffer area assigned in the field 
statement. So, for example, the statement: 

10 PRINT WD$! i MEANINGS 

displays the contents of the two buffer fields defined above. 

These values are meaningless unless we first place data in the buffer, lset, rset 
and get can all be used to accomplish this function. We’ll start with lset and 
rset, which are used in preparation for disk output. 

Our first entry is the word “left-justify” followed by its definition. 

100 0PEN"R"> 1» "GLOSSARY/BAS" 

110 FIELD 1, IS AS WD$* 240 AS MEANING* 

120 LSET WD*="LEFT-JUSTIFY" 

130 LSET MEANING$="TO PLACE A VALUE IN A FIELD FROM LEFT TO 
RIGHT5 IF THE DATA DOESN'T FILL THE FIELD* BLANKS ARE 
ADDED ON THE RIGHT 5 IF THE DATA IS TOO LONG* THE EXTRA 
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CHARACTERS ON THE RIGHT ARE IGNORED. LSET IS A LEFT- 
JUSTIFY FUNCTION." 

Line 120 left-justifies the value in quotes into the first field in buffer 1. Line 130 
does the same thing to its quoted string. 

Note: rset would place filler-blanks to the left of the item. Truncation would 
still be on the right. 

Now that the data is in the buffer, we can write it to disk with a simple put 
statement: 

140 PUT 1*1 
150 CLOSE 

This writes the first record into the file glossary/bas. 

To read and print the first record in glossary/bas, use the following sequence: 

1G0 0PEN“R"» 1> "GLOSSARY/BAS" 

170 FIELD 1» 1G AS HD*» 240 AS MEANING* 

180 GET 1>1 

190 PRINT WD$: PRINT MEANING* 

200 CLOSE 

Line 160 and 170 are required only because we closed the file in line 150. If we 
hadn’t closed it, we could go directly to line 180. 
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Random Access: A General 
Procedure 

The previous example shows the necessary sequences to read and write using 
random access. But it does not demonstrate the primary advantages of this form 
of access — in particular, it doesn’t show how to update existing files by going 
directly to the desired record. 

The program below, glossacc/bas, develops the glossary example to show 
some of the techniques of random access for file maintenance. But before 
looking at the program, study this general procedure for creating and 
maintaining files via random access. 


Step 

See GLOSSACC/BAS, 
Line Number 

1. Open the file 

110 

2. Field the buffer 

120 

3. Get the record to be updated 

140 

4. Display current contents of the record (use 

145-170 

CVD, CVI, CVS before displaying numeric 


data) 


5. LSET and RSET new values into the fields 

210-230 

(use MKD$, MKI$, MKS$ with numeric data 


before setting it into the buffer) 


6. PUT the updated record 

240 

7. To update another record, continue at step 3. 

250-260 

Otherwise, go to step 8. 


8. Close the file 

270 


112 ) 

100 

110 

120 

130 

140 

145 

150 

1G0 

170 

180 

190 


200 

210 

220 


REM . GLOSSACC/BAS ... 

CLS : CLEAR 300 

OPEN "R "t 1, "GLOSSARY/BAS" 

FIELD If 1G AS WD*. 238 AS MEANING*. 2 AS NX* 

INPUT "WHAT RECORD DO YOU WANT TO ACCESS"5 RX 
GET 1 . RX 

NXX = CO I(NX*) 'SAME LINK TO NEXT ALPHABETICAL ENTRY 
PRINT "WORD : "WD* 

PRINT "DEF'N : " : PRINT MEANING* 

PRINT "NEXT ALPHABETICAL ENTRY: RECORD NXX : PRINT 


: INPUT 

"TYPE 

NEW 

WORD 

<ENTER> 

OR 

<ENTER> 

IF OK" 

: PRINT 

"TYPE 

NEW 

DEF'N 

<ENTER> 

OR 

<ENTER> 

IF 


OK?" : LINE INPUT D* 

INPUT "TYPE NEW SEQUENCE NUMBER OR <ENTER> IF OK"5 NXX 
IF W* <> "" THEN LSET WD* = W* 

IF D* <> "" THEN LSET MEANING* = D* 
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r> 


230 LSET NX* = MKI* (NXX) 

240 PUT 1. RX 

245 RX = NXX 'USE NEXT ALPHA. LINK AS DEFAULT FOR NEXT RECORD 
250 CLS : PRINT " TYPE <ENTER> TO READ NEXT ALPHA. ENTRY 

PRINT" OR RECORD * <ENTER> FOR SPECIFIC ENTRY.": INPUT " 
OR 0 <ENTER) TO QUIT"! RX 
2S0 IF 0<RX THEN 140 
270 CLOSE 
280 END 

Notice we’ve added a field, nx$, to the record (line 120). nx$ will contain the 
number of the record which comes next in alphabetical sequence. This enables 
us to proceed alphabetically through the glossary, provided we know which 
record contains the entry which should come first. 

For example, suppose the glossary contains: 


record# 

word (WD$) 

defn, 

pointer to next 
alpha, entry (NX$) 

1 

LEFT-JUSTIFY 


3 

2 

BYTE 


4 

3 

RIGHT-JUSTIFY 


0 

4 

HEXADECIMAL 


1 


When we read record 2 (byte), it tells us that record 4 (hexadecimal) is next, 
which then tells us record 1 (left-justify) is next, etc. The last entry, record 3 
(right-justify), points us to zero, which we take to mean “The End.” 

Since nx$ will contain an integer, we have to first convert that number to a two- 
byte string representation, using mki$ (line 230 above). 

The following program displays the glossary in alphabetical sequence: 


300 REM ... GL0SS0UT/BAS ... 

310 CLS : CLEAR 300 

320 OPEN "R" . 1 . "GLOSSARY/BAS" 

330 FIELD 1. 1G AS WD* . 238 AS MEANING*» 2 AS NX* 
340 INPUT "WHICH RECORD IS FIRST ALPHABETICALLY"! 
350 GET 1 . NX 
380 PRINT : PRINT WD* 

370 PRINT MEANING* 

380 NX = COI(NX*) 

380 INPUT "PRESS <ENTER> TO CONTINUE"! X 
400 IF NX <> 0 THEN 350 
410 CLOSE 
420 END 


NX 
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Disk BASIC Error Codes/Messages 

51 Field overflow 

52 Internal error 

53 Bad file number 

54 File not found 

55 Bad file mode 

58 Disk i/o error 

62 Disk full 

63 Input past end 

64 Bad record number 

65 Bad file name 

67 Direct statement in file 

68 Too many files 

69 Disk write-protect 

70 File access 

Note: Disk errors cannot be simulated via the error statement. 
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Radio Shack Software License 

The following are the terms and conditions of the Radio Shack Software License for 
copies of Radio Shack software either purchased by the customer, or received with 
or as part of hardware purchased by customer: 

A. Radio Shack grants to CUSTOMER a personal, non-exclusive, paid up license to 
use the Radio Shack computer software programs received. Title to the media 
on which the software is recorded (cassette and/or disk) or stored (ROM) is 
transferred to the CUSTOMER, but not title to the software. 

B. In consideration for this license, CUSTOMER shall not reproduce copies of such 
software programs except to produce the number of copies required for 
personal use by CUSTOMER (if the software allows a backup copy to be made), 
and to include Radio Shack’s copyright notice on all copies of programs 
reproduced in whole or in part. 

C. CUSTOMER may resell Radio Shack's system and applications software 
(modified or not, in whole or in part), provided CUSTOMER has purchased one 
copy of the software for each one resold. The provisions of this Software 
License (paragraphs A, B, and C) shall also be applicable to third parties 
purchasing such software from CUSTOMER. 

Important Note 

All Radio Shack computer programs are licensed on an “as is” basis without 
warranty. 

Radio Shack shall have no liability or responsibility to customer or any other person 
or entity with respect to any liability, loss or damage caused or alleged to be caused 
directly or indirectly by computer equipment or programs sold by Radio Shack, 
including but not limited to any interruption of service, loss of business or 
anticipatory profits or consequential damages resulting from the use or operation of 
such computer or computer programs. 

Good data processing procedure dictates that the user test the program. run and test 
sample sets of data, and run the system in parallel with the system previously in use 
for a period of time adequate to insure that results of operation of the computer or 
program are satisfactory. 
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Service Policy 

Radio Shack’s nationwide network of service facilities provides quick, convenient, 
and reliable repair services for all of its computer products, in most instances. 
Warranty service will be performed in accordance with Radio Shack’s Limited 
Warranty. Non-warranty service will be provided at reasonable parts and labor 
costs. 

Because of the sensitivity of computer equipment, and the problems which can 
result from improper servicing, the following limitations also apply to the services 
offered by Radio Shack: 

1. If any of the warranty seals on any Radio Shack computer products are broken. 
Radio Shack reserves the right to refuse to service the equipment or to void any 
remaining warranty on the equipment. 

2. If any Radio Shack computer equipment has been modified so that it is not 
within manufacturer’s specifications, including, but not limited to, the 
installation of any non-Radio Shack parts, components, or replacement boards, 
then Radio Shack reserves the right to refuse to service the equipment, void any 
remaining warranty, remove and replace any non-Radio Shack part found in the 
equipment, and perform whatever modifications are necessary to return the 
equipment to original factory manufacturer’s specifications. 

3. The cost for the labor and parts required to return the Radio Shack computer 
equipment to original manufacturer’s specifications will be charged to the 
customer in addition to the normal repair charge. 
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IMPORTANT NOTICE 


ALL RADIO SHACK COMPUTER PROGRAMS ARE LICENSED ON AN 
“AS IS” BASIS WITHOUT WARRANTY. 

Radio Shack shall have no liability or responsibility to customer or any 
other person or entity with respect to any liability, loss or damage caused 
or alleged to be caused directly or indirectly by computer equipment or 
programs sold by Radio Shack, including but not limited to any interrup¬ 
tion of service, loss of business or anticipatory profits or consequential 
damages resulting from the use or operation of such computer or 
computer programs. 

NOTE: Good data processing procedure dictates that the user test the 
program, run and test sample sets of data, and run the system in 
parallel with the system previously in use for a period of time 
adequate to insure that results of operation of the computer or 
program are satisfactory. 

RADIO SHACK SOFTWARE LICENSE 

A. Radio Shack grants to CUSTOMER a non-exclusive, paid up license to 
use on CUSTOMER’S computer the Radio Shack computer software 
received. Title to the media on which the software is recorded (cassette 
and/or disk) or stored (ROM) is transferred to the CUSTOMER, but not 
title to the software. 

B. In consideration for this license, CUSTOMER shall not reproduce 
copies of Radio Shack software except to reproduce the number of copies 
required for use on CUSTOMER’S computer (if the software allows a 
backup copy to be made), and shall include Radio Shack’s copyright 
notice on all copies of software reproduced in whole or in part. 

C. CUSTOMER may resell Radio Shack’s system and applications soft¬ 
ware (modified or not, in whole or in part), provided CUSTOMER has 
purchased one copy of the software for each one resold. The provisions 
of this software License (paragraphs A, B.and C) shall also be applicable 
to third parties purchasing such software from CUSTOMER. 
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LIMITED WARRANTY 

For a period of 90 days from the date of delivery, Radio Shack warrants to the 
original purchaser that the computer hardware unit shall be free from manufac¬ 
turing defects. This warranty is only applicable to the original purchaser who 
purchased the unit from Radio Shack company-owned retail outlets or duly 
authorized Radio Shack franchisees and dealers. This warranty is voided if the 
unit is sold or transferred by purchaser to a third party. This warranty shall be 
void if this unit’s case or cabinet is opened, if the unit has been subjected to 
improper o r bnormal use, or if the unit is altered or modified. If a defect occurs 
during the irranty period, the unit must be returned to a Radio Shack store, 
franchisee, or dealer for repair, along with the sales ticket or lease agreement. 
Purchaser’s sole and exclusive remedy in the event of defect is limited to the 
correction of the defect by adjustment, repair, replacement, or complete 
refund at Radio Shack's election and sole expense. Radio Shack shall have no 
obligation to replace or repair expendable items. 

Any statements made by Radio Shack and its employees, including but not 
limited to, statements regarding capacity, suitability for use, or performance of 
the unit shall not be deemed a warranty or representation by Radio Shack for 
any purpose, nor give rise to any liability or obligation of Radio Shack. 

EXCEPT AS SPECIFICALLY PROVIDED IN THIS WARRANTY OR IN THE 
RADIO SHACK COMPUTER SALES AGREEMENT, THERE ARE NO 
OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT 
LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 
FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL RADIO 
SHACK BE LIABLE FOR LOSS OF PROFITS OR BENEFITS, INDIRECT, 
SPECIAL, CONSEQUENTIAL OR OTHER SIMILAR DAMAGES ARISING 
OUT OF ANY BREACH OF THIS WARRANTY OR OTHERWISE. 


7-80 


w m 


r* 


RADIO SHACK B A DIVISION OF TANDY CORPORATION 

Q 


U.S.A.: FORT WORTH, TEXAS 76102 
CANADA: BARRIE, ONTARIO L4M 4W5 

TANDY CORPORATION 


AUSTRALIA BELGIUM _ _ U.K. _ 

280-316 VICTORIA ROAD PARC INDUSTRIEL DE NANINNE BILSTON ROAD WEDNESBURY 

RYDALMERE, N.S.W. 2116 5140 NANINNE WEST MIDLANDS WS10 7JN 




8749167-581-SP 


PRINTED IN U.S.A. 


















